Make the R6RS simple I/O library use conditions
[bpt/guile.git] / doc / ref / r6rs.texi
1 @c -*-texinfo-*-
2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 2010, 2011
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
6
7 @node R6RS Support
8 @section R6RS Support
9 @cindex R6RS
10
11 @xref{R6RS Libraries}, for more information on how to define R6RS libraries, and
12 their integration with Guile modules.
13
14 @menu
15 * R6RS Incompatibilities:: Guile mostly implements R6RS.
16 * R6RS Standard Libraries:: Modules defined by the R6RS.
17 @end menu
18
19 @node R6RS Incompatibilities
20 @subsection Incompatibilities with the R6RS
21
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.
26
27 @itemize
28 @item
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.
33
34 @item
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.
38
39 @item
40 R6RS unicode escapes within strings are disabled by default, because
41 they conflict with Guile's already-existing escapes. The same is the
42 case for R6RS treatment of escaped newlines in strings.
43
44 R6RS behavior can be turned on via a reader option. @xref{String
45 Syntax}, for more information.
46
47 @item
48 A @code{set!} to a variable transformer may only expand to an
49 expression, not a definition---even if the original @code{set!}
50 expression was in definition context.
51
52 @item
53 Instead of using the algorithm detailed in chapter 10 of the R6RS,
54 expansion of toplevel forms happens sequentially.
55
56 For example, while the expansion of the following set of toplevel
57 definitions does the correct thing:
58
59 @example
60 (begin
61 (define even?
62 (lambda (x)
63 (or (= x 0) (odd? (- x 1)))))
64 (define-syntax odd?
65 (syntax-rules ()
66 ((odd? x) (not (even? x)))))
67 (even? 10))
68 @result{} #t
69 @end example
70
71 @noindent
72 The same definitions outside of the @code{begin} wrapper do not:
73
74 @example
75 (define even?
76 (lambda (x)
77 (or (= x 0) (odd? (- x 1)))))
78 (define-syntax odd?
79 (syntax-rules ()
80 ((odd? x) (not (even? x)))))
81 (even? 10)
82 <unnamed port>:4:18: In procedure even?:
83 <unnamed port>:4:18: Wrong type to apply: #<syntax-transformer odd?>
84 @end example
85
86 This is because when expanding the right-hand-side of @code{even?}, the
87 reference to @code{odd?} is not yet marked as a syntax transformer, so
88 it is assumed to be a function.
89
90 This bug will only affect top-level programs, not code in @code{library}
91 forms. Fixing it for toplevel forms seems doable, but tricky to
92 implement in a backward-compatible way. Suggestions and/or patches would
93 be appreciated.
94
95 @item
96 The @code{(rnrs io ports)} module is incomplete. Work is
97 ongoing to fix this.
98
99 @item
100 Guile does not prevent use of textual I/O procedures on binary ports.
101 More generally, it does not make a sharp distinction between binary and
102 textual ports (@pxref{R6RS Port Manipulation, binary-port?}).
103 @end itemize
104
105 @node R6RS Standard Libraries
106 @subsection R6RS Standard Libraries
107
108 In contrast with earlier versions of the Revised Report, the R6RS
109 organizes the procedures and syntactic forms required of conforming
110 implementations into a set of ``standard libraries'' which can be
111 imported as necessary by user programs and libraries. Here we briefly
112 list the libraries that have been implemented for Guile.
113
114 We do not attempt to document these libraries fully here, as most of
115 their functionality is already available in Guile itself. The
116 expectation is that most Guile users will use the well-known and
117 well-documented Guile modules. These R6RS libraries are mostly useful
118 to users who want to port their code to other R6RS systems.
119
120 The documentation in the following sections reproduces some of the
121 content of the library section of the Report, but is mostly intended to
122 provide supplementary information about Guile's implementation of the
123 R6RS standard libraries. For complete documentation, design rationales
124 and further examples, we advise you to consult the ``Standard
125 Libraries'' section of the Report (@pxref{Standard Libraries,
126 R6RS Standard Libraries,, r6rs, The Revised^6 Report on the Algorithmic
127 Language Scheme}).
128
129 @menu
130 * Library Usage:: What to know about Guile's library support.
131 * rnrs base:: The base library.
132 * rnrs unicode:: Access to Unicode operations.
133 * rnrs bytevectors:: Functions for working with binary data.
134 * rnrs lists:: List utilities.
135 * rnrs sorting:: Sorting for lists and vectors.
136 * rnrs control:: Additional control structures.
137
138 * R6RS Records:: A note about R6RS records.
139 * rnrs records syntactic:: Syntactic API for R6RS records.
140 * rnrs records procedural:: Procedural API for R6RS records.
141 * rnrs records inspection:: Reflection on R6RS records.
142
143 * rnrs exceptions:: Handling exceptional situations.
144 * rnrs conditions:: Data structures for exceptions.
145
146 * I/O Conditions:: Predefined I/O error types.
147 * rnrs io ports:: Support for port-based I/O.
148 * rnrs io simple:: High-level I/O API.
149
150 * rnrs files:: Functions for working with files.
151 * rnrs programs:: Functions for working with processes.
152 * rnrs arithmetic fixnums:: Fixed-precision arithmetic operations.
153 * rnrs arithmetic flonums:: Floating-point arithmetic operations.
154 * rnrs arithmetic bitwise:: Exact bitwise arithmetic operations.
155 * rnrs syntax-case:: Support for `syntax-case' macros.
156 * rnrs hashtables:: Hashtables.
157 * rnrs enums:: Enumerations.
158 * rnrs:: The composite library.
159 * rnrs eval:: Support for on-the-fly evaluation.
160 * rnrs mutable-pairs:: Support for mutable pairs.
161 * rnrs mutable-strings:: Support for mutable strings.
162 * rnrs r5rs:: Compatibility layer for R5RS Scheme.
163
164 @end menu
165
166 @node Library Usage
167 @subsubsection Library Usage
168
169 Guile implements the R6RS `library' form as a transformation to a native
170 Guile module definition. As a consequence of this, all of the libraries
171 described in the following subsections, in addition to being available
172 for use by R6RS libraries and top-level programs, can also be imported
173 as if they were normal Guile modules---via a @code{use-modules} form,
174 say. For example, the R6RS ``composite'' library can be imported by:
175
176 @lisp
177 (import (rnrs (6)))
178 @end lisp
179
180 @lisp
181 (use-modules ((rnrs) :version (6)))
182 @end lisp
183
184 For more information on Guile's library implementation, see
185 (@pxref{R6RS Libraries}).
186
187 @node rnrs base
188 @subsubsection rnrs base
189
190 The @code{(rnrs base (6))} library exports the procedures and syntactic
191 forms described in the main section of the Report
192 (@pxref{Base library, R6RS Base library,, r6rs,
193 The Revised^6 Report on the Algorithmic Language Scheme}). They are
194 grouped below by the existing manual sections to which they correspond.
195
196 @deffn {Scheme Procedure} boolean? obj
197 @deffnx {Scheme Procedure} not x
198 @xref{Booleans}, for documentation.
199 @end deffn
200
201 @deffn {Scheme Procedure} symbol? obj
202 @deffnx {Scheme Procedure} symbol->string sym
203 @deffnx {Scheme Procedure} string->symbol str
204 @xref{Symbol Primitives}, for documentation.
205 @end deffn
206
207 @deffn {Scheme Procedure} char? obj
208 @deffnx {Scheme Procedure} char=?
209 @deffnx {Scheme Procedure} char<?
210 @deffnx {Scheme Procedure} char>?
211 @deffnx {Scheme Procedure} char<=?
212 @deffnx {Scheme Procedure} char>=?
213 @deffnx {Scheme Procedure} integer->char n
214 @deffnx {Scheme Procedure} char->integer chr
215 @xref{Characters}, for documentation.
216 @end deffn
217
218 @deffn {Scheme Procedure} list? x
219 @deffnx {Scheme Procedure} null? x
220 @xref{List Predicates}, for documentation.
221 @end deffn
222
223 @deffn {Scheme Procedure} pair? x
224 @deffnx {Scheme Procedure} cons x y
225 @deffnx {Scheme Procedure} car pair
226 @deffnx {Scheme Procedure} cdr pair
227 @deffnx {Scheme Procedure} caar pair
228 @deffnx {Scheme Procedure} cadr pair
229 @deffnx {Scheme Procedure} cdar pair
230 @deffnx {Scheme Procedure} cddr pair
231 @deffnx {Scheme Procedure} caaar pair
232 @deffnx {Scheme Procedure} caadr pair
233 @deffnx {Scheme Procedure} cadar pair
234 @deffnx {Scheme Procedure} cdaar pair
235 @deffnx {Scheme Procedure} caddr pair
236 @deffnx {Scheme Procedure} cdadr pair
237 @deffnx {Scheme Procedure} cddar pair
238 @deffnx {Scheme Procedure} cdddr pair
239 @deffnx {Scheme Procedure} caaaar pair
240 @deffnx {Scheme Procedure} caaadr pair
241 @deffnx {Scheme Procedure} caadar pair
242 @deffnx {Scheme Procedure} cadaar pair
243 @deffnx {Scheme Procedure} cdaaar pair
244 @deffnx {Scheme Procedure} cddaar pair
245 @deffnx {Scheme Procedure} cdadar pair
246 @deffnx {Scheme Procedure} cdaadr pair
247 @deffnx {Scheme Procedure} cadadr pair
248 @deffnx {Scheme Procedure} caaddr pair
249 @deffnx {Scheme Procedure} caddar pair
250 @deffnx {Scheme Procedure} cadddr pair
251 @deffnx {Scheme Procedure} cdaddr pair
252 @deffnx {Scheme Procedure} cddadr pair
253 @deffnx {Scheme Procedure} cdddar pair
254 @deffnx {Scheme Procedure} cddddr pair
255 @xref{Pairs}, for documentation.
256 @end deffn
257
258 @deffn {Scheme Procedure} number? obj
259 @xref{Numerical Tower}, for documentation.
260 @end deffn
261
262 @deffn {Scheme Procedure} string? obj
263 @xref{String Predicates}, for documentation.
264 @end deffn
265
266 @deffn {Scheme Procedure} procedure? obj
267 @xref{Procedure Properties}, for documentation.
268 @end deffn
269
270 @deffn {Scheme Syntax} define name value
271 @deffnx {Scheme Syntax} set! variable-name value
272 @xref{Definition}, for documentation.
273 @end deffn
274
275 @deffn {Scheme Syntax} define-syntax keyword expression
276 @deffnx {Scheme Syntax} let-syntax ((keyword transformer) ...) exp ...
277 @deffnx {Scheme Syntax} letrec-syntax ((keyword transformer) ...) exp ...
278 @xref{Defining Macros}, for documentation.
279 @end deffn
280
281 @deffn {Scheme Syntax} identifier-syntax exp
282 @xref{Identifier Macros}, for documentation.
283 @end deffn
284
285 @deffn {Scheme Syntax} syntax-rules literals (pattern template) ...
286 @xref{Syntax Rules}, for documentation.
287 @end deffn
288
289 @deffn {Scheme Syntax} lambda formals body
290 @xref{Lambda}, for documentation.
291 @end deffn
292
293 @deffn {Scheme Syntax} let bindings body
294 @deffnx {Scheme Syntax} let* bindings body
295 @deffnx {Scheme Syntax} letrec bindings body
296 @deffnx {Scheme Syntax} letrec* bindings body
297 @xref{Local Bindings}, for documentation.
298 @end deffn
299
300 @deffn {Scheme Syntax} let-values bindings body
301 @deffnx {Scheme Syntax} let*-values bindings body
302 @xref{SRFI-11}, for documentation.
303 @end deffn
304
305 @deffn {Scheme Syntax} begin expr1 expr2 ...
306 @xref{begin}, for documentation.
307 @end deffn
308
309 @deffn {Scheme Syntax} quote expr
310 @deffnx {Scheme Syntax} quasiquote expr
311 @deffnx {Scheme Syntax} unquote expr
312 @deffnx {Scheme Syntax} unquote-splicing expr
313 @xref{Expression Syntax}, for documentation.
314 @end deffn
315
316 @deffn {Scheme Syntax} if test consequence [alternate]
317 @deffnx {Scheme Syntax} cond clause1 clause2 ...
318 @deffnx {Scheme Syntax} case key clause1 clause2 ...
319 @xref{if cond case}, for documentation.
320 @end deffn
321
322 @deffn {Scheme Syntax} and expr ...
323 @deffnx {Scheme Syntax} or expr ...
324 @xref{and or}, for documentation.
325 @end deffn
326
327 @deffn {Scheme Procedure} eq? x y
328 @deffnx {Scheme Procedure} eqv? x y
329 @deffnx {Scheme Procedure} equal? x y
330 @deffnx {Scheme Procedure} symbol=? symbol1 symbol2 ...
331 @xref{Equality}, for documentation.
332
333 @code{symbol=?} is identical to @code{eq?}.
334 @end deffn
335
336 @deffn {Scheme Procedure} complex? z
337 @xref{Complex Numbers}, for documentation.
338 @end deffn
339
340 @deffn {Scheme Procedure} real-part z
341 @deffnx {Scheme Procedure} imag-part z
342 @deffnx {Scheme Procedure} make-rectangular real_part imaginary_part
343 @deffnx {Scheme Procedure} make-polar x y
344 @deffnx {Scheme Procedure} magnitude z
345 @deffnx {Scheme Procedure} angle z
346 @xref{Complex}, for documentation.
347 @end deffn
348
349 @deffn {Scheme Procedure} sqrt z
350 @deffnx {Scheme Procedure} exp z
351 @deffnx {Scheme Procedure} expt z1 z2
352 @deffnx {Scheme Procedure} log z
353 @deffnx {Scheme Procedure} sin z
354 @deffnx {Scheme Procedure} cos z
355 @deffnx {Scheme Procedure} tan z
356 @deffnx {Scheme Procedure} asin z
357 @deffnx {Scheme Procedure} acos z
358 @deffnx {Scheme Procedure} atan z
359 @xref{Scientific}, for documentation.
360 @end deffn
361
362 @deffn {Scheme Procedure} real? x
363 @deffnx {Scheme Procedure} rational? x
364 @deffnx {Scheme Procedure} numerator x
365 @deffnx {Scheme Procedure} denominator x
366 @deffnx {Scheme Procedure} rationalize x eps
367 @xref{Reals and Rationals}, for documentation.
368 @end deffn
369
370 @deffn {Scheme Procedure} exact? x
371 @deffnx {Scheme Procedure} inexact? x
372 @deffnx {Scheme Procedure} exact z
373 @deffnx {Scheme Procedure} inexact z
374 @xref{Exactness}, for documentation. The @code{exact} and
375 @code{inexact} procedures are identical to the @code{inexact->exact} and
376 @code{exact->inexact} procedures provided by Guile's code library.
377 @end deffn
378
379 @deffn {Scheme Procedure} integer? x
380 @xref{Integers}, for documentation.
381 @end deffn
382
383 @deffn {Scheme Procedure} odd? n
384 @deffnx {Scheme Procedure} even? n
385 @deffnx {Scheme Procedure} gcd x ...
386 @deffnx {Scheme Procedure} lcm x ...
387 @deffnx {Scheme Procedure} exact-integer-sqrt k
388 @xref{Integer Operations}, for documentation.
389 @end deffn
390
391 @deffn {Scheme Procedure} =
392 @deffnx {Scheme Procedure} <
393 @deffnx {Scheme Procedure} >
394 @deffnx {Scheme Procedure} <=
395 @deffnx {Scheme Procedure} >=
396 @deffnx {Scheme Procedure} zero? x
397 @deffnx {Scheme Procedure} positive? x
398 @deffnx {Scheme Procedure} negative? x
399 @xref{Comparison}, for documentation.
400 @end deffn
401
402 @deffn {Scheme Procedure} for-each f lst1 lst2 ...
403 @xref{SRFI-1 Fold and Map}, for documentation.
404 @end deffn
405
406 @deffn {Scheme Procedure} list elem1 ... elemN
407 @xref{List Constructors}, for documentation.
408 @end deffn
409
410 @deffn {Scheme Procedure} length lst
411 @deffnx {Scheme Procedure} list-ref lst k
412 @deffnx {Scheme Procedure} list-tail lst k
413 @xref{List Selection}, for documentation.
414 @end deffn
415
416 @deffn {Scheme Procedure} append lst1 ... lstN
417 @deffnx {Scheme Procedure} reverse lst
418 @xref{Append/Reverse}, for documentation.
419 @end deffn
420
421 @deffn {Scheme Procedure} number->string n [radix]
422 @deffnx {Scheme Procedure} string->number str [radix]
423 @xref{Conversion}, for documentation.
424 @end deffn
425
426 @deffn {Scheme Procedure} string char ...
427 @deffnx {Scheme Procedure} make-string k [chr]
428 @deffnx {Scheme Procedure} list->string lst
429 @xref{String Constructors}, for documentation.
430 @end deffn
431
432 @deffn {Scheme Procedure} string->list str [start [end]]
433 @xref{List/String Conversion}, for documentation.
434 @end deffn
435
436 @deffn {Scheme Procedure} string-length str
437 @deffnx {Scheme Procedure} string-ref str k
438 @deffnx {Scheme Procedure} string-copy str [start [end]]
439 @deffnx {Scheme Procedure} substring str start [end]
440 @xref{String Selection}, for documentation.
441 @end deffn
442
443 @deffn {Scheme Procedure} string=? [s1 [s2 . rest]]
444 @deffnx {Scheme Procedure} string<? [s1 [s2 . rest]]
445 @deffnx {Scheme Procedure} string>? [s1 [s2 . rest]]
446 @deffnx {Scheme Procedure} string<=? [s1 [s2 . rest]]
447 @deffnx {Scheme Procedure} string>=? [s1 [s2 . rest]]
448 @xref{String Comparison}, for documentation.
449 @end deffn
450
451 @deffn {Scheme Procedure} string-append . args
452 @xref{Reversing and Appending Strings}, for documentation.
453 @end deffn
454
455 @deffn {Scheme Procedure} string-for-each proc s [start [end]]
456 @xref{Mapping Folding and Unfolding}, for documentation.
457 @end deffn
458
459 @deffn {Scheme Procedure} + z1 ...
460 @deffnx {Scheme Procedure} - z1 z2 ...
461 @deffnx {Scheme Procedure} * z1 ...
462 @deffnx {Scheme Procedure} / z1 z2 ...
463 @deffnx {Scheme Procedure} max x1 x2 ...
464 @deffnx {Scheme Procedure} min x1 x2 ...
465 @deffnx {Scheme Procedure} abs x
466 @deffnx {Scheme Procedure} truncate x
467 @deffnx {Scheme Procedure} floor x
468 @deffnx {Scheme Procedure} ceiling x
469 @deffnx {Scheme Procedure} round x
470 @xref{Arithmetic}, for documentation.
471 @end deffn
472
473 @rnindex div
474 @rnindex mod
475 @rnindex div-and-mod
476 @deffn {Scheme Procedure} div x y
477 @deffnx {Scheme Procedure} mod x y
478 @deffnx {Scheme Procedure} div-and-mod x y
479 These procedures accept two real numbers @var{x} and @var{y}, where the
480 divisor @var{y} must be non-zero. @code{div} returns the integer @var{q}
481 and @code{mod} returns the real number @var{r} such that
482 @math{@var{x} = @var{q}*@var{y} + @var{r}} and @math{0 <= @var{r} < abs(@var{y})}.
483 @code{div-and-mod} returns both @var{q} and @var{r}, and is more
484 efficient than computing each separately. Note that when @math{@var{y} > 0},
485 @code{div} returns @math{floor(@var{x}/@var{y})}, otherwise
486 it returns @math{ceiling(@var{x}/@var{y})}.
487
488 @lisp
489 (div 123 10) @result{} 12
490 (mod 123 10) @result{} 3
491 (div-and-mod 123 10) @result{} 12 and 3
492 (div-and-mod 123 -10) @result{} -12 and 3
493 (div-and-mod -123 10) @result{} -13 and 7
494 (div-and-mod -123 -10) @result{} 13 and 7
495 (div-and-mod -123.2 -63.5) @result{} 2.0 and 3.8
496 (div-and-mod 16/3 -10/7) @result{} -3 and 22/21
497 @end lisp
498 @end deffn
499
500 @rnindex div0
501 @rnindex mod0
502 @rnindex div0-and-mod0
503 @deffn {Scheme Procedure} div0 x y
504 @deffnx {Scheme Procedure} mod0 x y
505 @deffnx {Scheme Procedure} div0-and-mod0 x y
506 These procedures accept two real numbers @var{x} and @var{y}, where the
507 divisor @var{y} must be non-zero. @code{div0} returns the
508 integer @var{q} and @code{mod0} returns the real number
509 @var{r} such that @math{@var{x} = @var{q}*@var{y} + @var{r}} and
510 @math{-abs(@var{y}/2) <= @var{r} < abs(@var{y}/2)}. @code{div0-and-mod0}
511 returns both @var{q} and @var{r}, and is more efficient than computing
512 each separately.
513
514 Note that @code{div0} returns @math{@var{x}/@var{y}} rounded to the
515 nearest integer. When @math{@var{x}/@var{y}} lies exactly half-way
516 between two integers, the tie is broken according to the sign of
517 @var{y}. If @math{@var{y} > 0}, ties are rounded toward positive
518 infinity, otherwise they are rounded toward negative infinity.
519 This is a consequence of the requirement that
520 @math{-abs(@var{y}/2) <= @var{r} < abs(@var{y}/2)}.
521
522 @lisp
523 (div0 123 10) @result{} 12
524 (mod0 123 10) @result{} 3
525 (div0-and-mod0 123 10) @result{} 12 and 3
526 (div0-and-mod0 123 -10) @result{} -12 and 3
527 (div0-and-mod0 -123 10) @result{} -12 and -3
528 (div0-and-mod0 -123 -10) @result{} 12 and -3
529 (div0-and-mod0 -123.2 -63.5) @result{} 2.0 and 3.8
530 (div0-and-mod0 16/3 -10/7) @result{} -4 and -8/21
531 @end lisp
532 @end deffn
533
534 @deffn {Scheme Procedure} real-valued? obj
535 @deffnx {Scheme Procedure} rational-valued? obj
536 @deffnx {Scheme Procedure} integer-valued? obj
537 These procedures return @code{#t} if and only if their arguments can,
538 respectively, be coerced to a real, rational, or integer value without a
539 loss of numerical precision.
540
541 @code{real-valued?} will return @code{#t} for complex numbers whose
542 imaginary parts are zero.
543 @end deffn
544
545 @deffn {Scheme Procedure} nan? x
546 @deffnx {Scheme Procedure} infinite? x
547 @deffnx {Scheme Procedure} finite? x
548 @code{nan?} returns @code{#t} if @var{x} is a NaN value, @code{#f}
549 otherwise. @code{infinite?} returns @code{#t} if @var{x} is an infinite
550 value, @code{#f} otherwise. @code{finite?} returns @code{#t} if @var{x}
551 is neither infinite nor a NaN value, otherwise it returns @code{#f}.
552 Every real number satisfies exactly one of these predicates. An
553 exception is raised if @var{x} is not real.
554 @end deffn
555
556 @deffn {Scheme Syntax} assert expr
557 Raises an @code{&assertion} condition if @var{expr} evaluates to
558 @code{#f}; otherwise evaluates to the value of @var{expr}.
559 @end deffn
560
561 @deffn {Scheme Procedure} error who message irritant1 ...
562 @deffnx {Scheme Procedure} assertion-violation who message irritant1 ...
563 These procedures raise compound conditions based on their arguments:
564 If @var{who} is not @code{#f}, the condition will include a @code{&who}
565 condition whose @code{who} field is set to @var{who}; a @code{&message}
566 condition will be included with a @code{message} field equal to
567 @var{message}; an @code{&irritants} condition will be included with its
568 @code{irritants} list given by @code{irritant1 ...}.
569
570 @code{error} produces a compound condition with the simple conditions
571 described above, as well as an @code{&error} condition;
572 @code{assertion-violation} produces one that includes an
573 @code{&assertion} condition.
574 @end deffn
575
576 @deffn {Scheme Procedure} vector-map proc v
577 @deffnx {Scheme Procedure} vector-for-each proc v
578 These procedures implement the @code{map} and @code{for-each} contracts
579 over vectors.
580 @end deffn
581
582 @deffn {Scheme Procedure} vector . l
583 @deffnx {Scheme Procedure} vector? obj
584 @deffnx {Scheme Procedure} make-vector len
585 @deffnx {Scheme Procedure} make-vector len fill
586 @deffnx {Scheme Procedure} list->vector l
587 @deffnx {Scheme Procedure} vector->list v
588 @xref{Vector Creation}, for documentation.
589 @end deffn
590
591 @deffn {Scheme Procedure} vector-length vector
592 @deffnx {Scheme Procedure} vector-ref vector k
593 @deffnx {Scheme Procedure} vector-set! vector k obj
594 @deffnx {Scheme Procedure} vector-fill! v fill
595 @xref{Vector Accessors}, for documentation.
596 @end deffn
597
598 @deffn {Scheme Procedure} call-with-current-continuation proc
599 @deffnx {Scheme Procedure} call/cc proc
600 @xref{Continuations}, for documentation.
601 @end deffn
602
603 @deffn {Scheme Procedure} values arg1 ... argN
604 @deffnx {Scheme Procedure} call-with-values producer consumer
605 @xref{Multiple Values}, for documentation.
606 @end deffn
607
608 @deffn {Scheme Procedure} dynamic-wind in_guard thunk out_guard
609 @xref{Dynamic Wind}, for documentation.
610 @end deffn
611
612 @deffn {Scheme Procedure} apply proc arg1 ... argN arglst
613 @xref{Fly Evaluation}, for documentation.
614 @end deffn
615
616 @node rnrs unicode
617 @subsubsection rnrs unicode
618
619 The @code{(rnrs unicode (6))} library provides procedures for
620 manipulating Unicode characters and strings.
621
622 @deffn {Scheme Procedure} char-upcase char
623 @deffnx {Scheme Procedure} char-downcase char
624 @deffnx {Scheme Procedure} char-titlecase char
625 @deffnx {Scheme Procedure} char-foldcase char
626 These procedures translate their arguments from one Unicode character
627 set to another. @code{char-upcase}, @code{char-downcase}, and
628 @code{char-titlecase} are identical to their counterparts in the
629 Guile core library; @xref{Characters}, for documentation.
630
631 @code{char-foldcase} returns the result of applying @code{char-upcase}
632 to its argument, followed by @code{char-downcase}---except in the case
633 of the Turkic characters @code{U+0130} and @code{U+0131}, for which the
634 procedure acts as the identity function.
635 @end deffn
636
637 @deffn {Scheme Procedure} char-ci=? char1 char2 char3 ...
638 @deffnx {Scheme Procedure} char-ci<? char1 char2 char3 ...
639 @deffnx {Scheme Procedure} char-ci>? char1 char2 char3 ...
640 @deffnx {Scheme Procedure} char-ci<=? char1 char2 char3 ...
641 @deffnx {Scheme Procedure} char-ci>=? char1 char2 char3 ...
642 These procedures facilitate case-insensitive comparison of Unicode
643 characters. They are identical to the procedures provided by Guile's
644 core library. @xref{Characters}, for documentation.
645 @end deffn
646
647 @deffn {Scheme Procedure} char-alphabetic? char
648 @deffnx {Scheme Procedure} char-numeric? char
649 @deffnx {Scheme Procedure} char-whitespace? char
650 @deffnx {Scheme Procedure} char-upper-case? char
651 @deffnx {Scheme Procedure} char-lower-case? char
652 @deffnx {Scheme Procedure} char-title-case? char
653 These procedures implement various Unicode character set predicates.
654 They are identical to the procedures provided by Guile's core library.
655 @xref{Characters}, for documentation.
656 @end deffn
657
658 @deffn {Scheme Procedure} char-general-category char
659 @xref{Characters}, for documentation.
660 @end deffn
661
662 @deffn {Scheme Procedure} string-upcase string
663 @deffnx {Scheme Procedure} string-downcase string
664 @deffnx {Scheme Procedure} string-titlecase string
665 @deffnx {Scheme Procedure} string-foldcase string
666 These procedures perform Unicode case folding operations on their input.
667 @xref{Alphabetic Case Mapping}, for documentation.
668 @end deffn
669
670 @deffn {Scheme Procedure} string-ci=? string1 string2 string3 ...
671 @deffnx {Scheme Procedure} string-ci<? string1 string2 string3 ...
672 @deffnx {Scheme Procedure} string-ci>? string1 string2 string3 ...
673 @deffnx {Scheme Procedure} string-ci<=? string1 string2 string3 ...
674 @deffnx {Scheme Procedure} string-ci>=? string1 string2 string3 ...
675 These procedures perform case-insensitive comparison on their input.
676 @xref{String Comparison}, for documentation.
677 @end deffn
678
679 @deffn {Scheme Procedure} string-normalize-nfd string
680 @deffnx {Scheme Procedure} string-normalize-nfkd string
681 @deffnx {Scheme Procedure} string-normalize-nfc string
682 @deffnx {Scheme Procedure} string-normalize-nfkc string
683 These procedures perform Unicode string normalization operations on
684 their input. @xref{String Comparison}, for documentation.
685 @end deffn
686
687 @node rnrs bytevectors
688 @subsubsection rnrs bytevectors
689
690 The @code{(rnrs bytevectors (6))} library provides procedures for
691 working with blocks of binary data. This functionality is documented
692 in its own section of the manual; @xref{Bytevectors}.
693
694 @node rnrs lists
695 @subsubsection rnrs lists
696
697 The @code{(rnrs lists (6))} library provides procedures additional
698 procedures for working with lists.
699
700 @deffn {Scheme Procedure} find proc list
701 This procedure is identical to the one defined in Guile's SRFI-1
702 implementation. @xref{SRFI-1 Searching}, for documentation.
703 @end deffn
704
705 @deffn {Scheme Procedure} for-all proc list1 list2 ...
706 @deffnx {Scheme Procedure} exists proc list1 list2 ...
707
708 The @code{for-all} procedure is identical to the @code{every} procedure
709 defined by SRFI-1; the @code{exists} procedure is identical to SRFI-1's
710 @code{any}. @xref{SRFI-1 Searching}, for documentation.
711 @end deffn
712
713 @deffn {Scheme Procedure} filter proc list
714 @deffnx {Scheme Procedure} partition proc list
715 These procedures are identical to the ones provided by SRFI-1.
716 @xref{List Modification}, for a description of @code{filter};
717 @xref{SRFI-1 Filtering and Partitioning}, for @code{partition}.
718 @end deffn
719
720 @deffn {Scheme Procedure} fold-left combine nil list1 list2 ... listn
721 @deffnx {Scheme Procedure} fold-right combine nil list1 list2 ... listn
722 These procedures are identical to the @code{fold} and @code{fold-right}
723 procedures provided by SRFI-1. @xref{SRFI-1 Fold and Map}, for
724 documentation.
725 @end deffn
726
727 @deffn {Scheme Procedure} remp proc list
728 @deffnx {Scheme Procedure} remove obj list
729 @deffnx {Scheme Procedure} remv obj list
730 @deffnx {Scheme Procedure} remq obj list
731 @code{remove}, @code{remv}, and @code{remq} are identical to the
732 @code{delete}, @code{delv}, and @code{delq} procedures provided by
733 Guile's core library, (@pxref{List Modification}). @code{remp} is
734 identical to the alternate @code{remove} procedure provided by SRFI-1;
735 @xref{SRFI-1 Deleting}.
736 @end deffn
737
738 @deffn {Scheme Procedure} memp proc list
739 @deffnx {Scheme Procedure} member obj list
740 @deffnx {Scheme Procedure} memv obj list
741 @deffnx {Scheme Procedure} memq obj list
742 @code{member}, @code{memv}, and @code{memq} are identical to the
743 procedures provided by Guile's core library; @xref{List Searching},
744 for their documentation. @code{memp} uses the specified predicate
745 function @code{proc} to test elements of the list @var{list}---it
746 behaves similarly to @code{find}, except that it returns the first
747 sublist of @var{list} whose @code{car} satisfies @var{proc}.
748 @end deffn
749
750 @deffn {Scheme Procedure} assp proc alist
751 @deffnx {Scheme Procedure} assoc obj alist
752 @deffnx {Scheme Procedure} assv obj alist
753 @deffnx {Scheme Procedure} assq obj alist
754 @code{assoc}, @code{assv}, and @code{assq} are identical to the
755 procedures provided by Guile's core library;
756 @xref{Alist Key Equality}, for their documentation. @code{assp} uses
757 the specified predicate function @code{proc} to test keys in the
758 association list @var{alist}.
759 @end deffn
760
761 @deffn {Scheme Procedure} cons* obj1 ... obj
762 @deffnx {Scheme Procedure} cons* obj
763 This procedure is identical to the one exported by Guile's core
764 library. @xref{List Constructors}, for documentation.
765 @end deffn
766
767 @node rnrs sorting
768 @subsubsection rnrs sorting
769
770 The @code{(rnrs sorting (6))} library provides procedures for sorting
771 lists and vectors.
772
773 @deffn {Scheme Procedure} list-sort proc list
774 @deffnx {Scheme Procedure} vector-sort proc vector
775 These procedures return their input sorted in ascending order, without
776 modifying the original data. @var{proc} must be a procedure that takes
777 two elements from the input list or vector as arguments, and returns a
778 true value if the first is ``less'' than the second, @code{#f}
779 otherwise. @code{list-sort} returns a list; @code{vector-sort} returns
780 a vector.
781
782 Both @code{list-sort} and @code{vector-sort} are implemented in terms of
783 the @code{stable-sort} procedure from Guile's core library.
784 @xref{Sorting}, for a discussion of the behavior of that procedure.
785 @end deffn
786
787 @deffn {Scheme Procedure} vector-sort! proc vector
788 Performs a destructive, ``in-place'' sort of @var{vector}, using
789 @var{proc} as described above to determine an ascending ordering of
790 elements. @code{vector-sort!} returns an unspecified value.
791
792 This procedure is implemented in terms of the @code{sort!} procedure
793 from Guile's core library. @xref{Sorting}, for more information.
794 @end deffn
795
796 @node rnrs control
797 @subsubsection rnrs control
798
799 The @code{(rnrs control (6))} library provides syntactic forms useful
800 for constructing conditional expressions and controlling the flow of
801 execution.
802
803 @deffn {Scheme Syntax} when test expression1 expression2 ...
804 @deffnx {Scheme Syntax} unless test expression1 expression2 ...
805 The @code{when} form is evaluated by evaluating the specified @var{test}
806 expression; if the result is a true value, the @var{expression}s that
807 follow it are evaluated in order, and the value of the final
808 @var{expression} becomes the value of the entire @code{when} expression.
809
810 The @code{unless} form behaves similarly, with the exception that the
811 specified @var{expression}s are only evaluated if the value of
812 @var{test} is false.
813 @end deffn
814
815 @deffn {Scheme Syntax} do ((variable init step) ...) (test expression ...) command ...
816 This form is identical to the one provided by Guile's core library.
817 @xref{while do}, for documentation.
818 @end deffn
819
820 @deffn {Scheme Syntax} case-lambda clause ...
821 This form is identical to the one provided by Guile's core library.
822 @xref{Case-lambda}, for documentation.
823 @end deffn
824
825 @node R6RS Records
826 @subsubsection R6RS Records
827
828 The manual sections below describe Guile's implementation of R6RS
829 records, which provide support for user-defined data types. The R6RS
830 records API provides a superset of the features provided by Guile's
831 ``native'' records, as well as those of the SRFI-9 records API;
832 @xref{Records}, and @ref{SRFI-9}, for a description of those
833 interfaces.
834
835 As with SRFI-9 and Guile's native records, R6RS records are constructed
836 using a record-type descriptor that specifies attributes like the
837 record's name, its fields, and the mutability of those fields.
838
839 R6RS records extend this framework to support single inheritance via the
840 specification of a ``parent'' type for a record type at definition time.
841 Accessors and mutator procedures for the fields of a parent type may be
842 applied to records of a subtype of this parent. A record type may be
843 @dfn{sealed}, in which case it cannot be used as the parent of another
844 record type.
845
846 The inheritance mechanism for record types also informs the process of
847 initializing the fields of a record and its parents. Constructor
848 procedures that generate new instances of a record type are obtained
849 from a record constructor descriptor, which encapsulates the record-type
850 descriptor of the record to be constructed along with a @dfn{protocol}
851 procedure that defines how constructors for record subtypes delegate to
852 the constructors of their parent types.
853
854 A protocol is a procedure used by the record system at construction time
855 to bind arguments to the fields of the record being constructed. The
856 protocol procedure is passed a procedure @var{n} that accepts the
857 arguments required to construct the record's parent type; this
858 procedure, when invoked, will return a procedure @var{p} that accepts
859 the arguments required to construct a new instance of the record type
860 itself and returns a new instance of the record type.
861
862 The protocol should in turn return a procedure that uses @var{n} and
863 @var{p} to initialize the fields of the record type and its parent
864 type(s). This procedure will be the constructor returned by
865
866 As a trivial example, consider the hypothetical record type
867 @code{pixel}, which encapsulates an x-y location on a screen, and
868 @code{voxel}, which has @code{pixel} as its parent type and stores an
869 additional coordinate. The following protocol produces a constructor
870 procedure that accepts all three coordinates, uses the first two to
871 initialize the fields of @code{pixel}, and binds the third to the single
872 field of @code{voxel}.
873
874 @lisp
875 (lambda (n)
876 (lambda (x y z)
877 (let ((p (n x y)))
878 (p z))))
879 @end lisp
880
881 It may be helpful to think of protocols as ``constructor factories''
882 that produce chains of delegating constructors glued together by the
883 helper procedure @var{n}.
884
885 An R6RS record type may be declared to be @dfn{nongenerative} via the
886 use of a unique generated or user-supplied symbol---or
887 @dfn{uid}---such that subsequent record type declarations with the same
888 uid and attributes will return the previously-declared record-type
889 descriptor.
890
891 R6RS record types may also be declared to be @dfn{opaque}, in which case
892 the various predicates and introspection procedures defined in
893 @code{(rnrs records introspection)} will behave as if records of this
894 type are not records at all.
895
896 Note that while the R6RS records API shares much of its namespace with
897 both the SRFI-9 and native Guile records APIs, it is not currently
898 compatible with either.
899
900 @node rnrs records syntactic
901 @subsubsection rnrs records syntactic
902
903 The @code{(rnrs records syntactic (6))} library exports the syntactic
904 API for working with R6RS records.
905
906 @deffn {Scheme Syntax} define-record-type name-spec record-clause*
907 Defines a new record type, introducing bindings for a record-type
908 descriptor, a record constructor descriptor, a constructor procedure,
909 a record predicate, and accessor and mutator procedures for the new
910 record type's fields.
911
912 @var{name-spec} must either be an identifier or must take the form
913 @code{(record-name constructor-name predicate-name)}, where
914 @var{record-name}, @var{constructor-name}, and @var{predicate-name} are
915 all identifiers and specify the names to which, respectively, the
916 record-type descriptor, constructor, and predicate procedures will be
917 bound. If @var{name-spec} is only an identifier, it specifies the name
918 to which the generated record-type descriptor will be bound.
919
920 Each @var{record-clause} must be one of the following:
921
922 @itemize @bullet
923 @item
924 @code{(fields field-spec*)}, where each @var{field-spec} specifies a
925 field of the new record type and takes one of the following forms:
926 @itemize @bullet
927 @item
928 @code{(immutable field-name accessor-name)}, which specifies an
929 immutable field with the name @var{field-name} and binds an accessor
930 procedure for it to the name given by @var{accessor-name}
931 @item
932 @code{(mutable field-name accessor-name mutator-name)}, which specifies
933 a mutable field with the name @var{field-name} and binds accessor and
934 mutator procedures to @var{accessor-name} and @var{mutator-name},
935 respectively
936 @item
937 @code{(immutable field-name)}, which specifies an immutable field with
938 the name @var{field-name}; an accessor procedure for it will be created
939 and named by appending record name and @var{field-name} with a hyphen
940 separator
941 @item
942 @code{(mutable field-name}), which specifies a mutable field with the
943 name @var{field-name}; an accessor procedure for it will be created and
944 named as described above; a mutator procedure will also be created and
945 named by appending @code{-set!} to the accessor name
946 @item
947 @code{field-name}, which specifies an immutable field with the name
948 @var{field-name}; an access procedure for it will be created and named
949 as described above
950 @end itemize
951 @item
952 @code{(parent parent-name)}, where @var{parent-name} is a symbol giving
953 the name of the record type to be used as the parent of the new record
954 type
955 @item
956 @code{(protocol expression)}, where @var{expression} evaluates to a
957 protocol procedure which behaves as described above, and is used to
958 create a record constructor descriptor for the new record type
959 @item
960 @code{(sealed sealed?)}, where @var{sealed?} is a boolean value that
961 specifies whether or not the new record type is sealed
962 @item
963 @code{(opaque opaque?)}, where @var{opaque?} is a boolean value that
964 specifies whether or not the new record type is opaque
965 @item
966 @code{(nongenerative [uid])}, which specifies that the record type is
967 nongenerative via the optional uid @var{uid}. If @var{uid} is not
968 specified, a unique uid will be generated at expansion time
969 @item
970 @code{(parent-rtd parent-rtd parent-cd)}, a more explicit form of the
971 @code{parent} form above; @var{parent-rtd} and @var{parent-cd} should
972 evaluate to a record-type descriptor and a record constructor
973 descriptor, respectively
974 @end itemize
975 @end deffn
976
977 @deffn {Scheme Syntax} record-type-descriptor record-name
978 Evaluates to the record-type descriptor associated with the type
979 specified by @var{record-name}.
980 @end deffn
981
982 @deffn {Scheme Syntax} record-constructor-descriptor record-name
983 Evaluates to the record-constructor descriptor associated with the type
984 specified by @var{record-name}.
985 @end deffn
986
987 @node rnrs records procedural
988 @subsubsection rnrs records procedural
989
990 The @code{(rnrs records procedural (6))} library exports the procedural
991 API for working with R6RS records.
992
993 @deffn {Scheme Procedure} make-record-type-descriptor name parent uid sealed? opaque? fields
994 Returns a new record-type descriptor with the specified characteristics:
995 @var{name} must be a symbol giving the name of the new record type;
996 @var{parent} must be either @code{#f} or a non-sealed record-type
997 descriptor for the returned record type to extend; @var{uid} must be
998 either @code{#f}, indicating that the record type is generative, or
999 a symbol giving the type's nongenerative uid; @var{sealed?} and
1000 @var{opaque?} must be boolean values that specify the sealedness and
1001 opaqueness of the record type; @var{fields} must be a vector of zero or
1002 more field specifiers of the form @code{(mutable name)} or
1003 @code{(immutable name)}, where name is a symbol giving a name for the
1004 field.
1005
1006 If @var{uid} is not @code{#f}, it must be a symbol
1007 @end deffn
1008
1009 @deffn {Scheme Procedure} record-type-descriptor? obj
1010 Returns @code{#t} if @var{obj} is a record-type descriptor, @code{#f}
1011 otherwise.
1012 @end deffn
1013
1014 @deffn {Scheme Procedure} make-record-constructor-descriptor rtd parent-constructor-descriptor protocol
1015 Returns a new record constructor descriptor that can be used to produce
1016 constructors for the record type specified by the record-type descriptor
1017 @var{rtd} and whose delegation and binding behavior are specified by the
1018 protocol procedure @var{protocol}.
1019
1020 @var{parent-constructor-descriptor} specifies a record constructor
1021 descriptor for the parent type of @var{rtd}, if one exists. If
1022 @var{rtd} represents a base type, then
1023 @var{parent-constructor-descriptor} must be @code{#f}. If @var{rtd}
1024 is an extension of another type, @var{parent-constructor-descriptor} may
1025 still be @code{#f}, but protocol must also be @code{#f} in this case.
1026 @end deffn
1027
1028 @deffn {Scheme Procedure} record-constructor rcd
1029 Returns a record constructor procedure by invoking the protocol
1030 defined by the record-constructor descriptor @var{rcd}.
1031 @end deffn
1032
1033 @deffn {Scheme Procedure} record-predicate rtd
1034 Returns the record predicate procedure for the record-type descriptor
1035 @var{rtd}.
1036 @end deffn
1037
1038 @deffn {Scheme Procedure} record-accessor rtd k
1039 Returns the record field accessor procedure for the @var{k}th field of
1040 the record-type descriptor @var{rtd}.
1041 @end deffn
1042
1043 @deffn {Scheme Procedure} record-mutator rtd k
1044 Returns the record field mutator procedure for the @var{k}th field of
1045 the record-type descriptor @var{rtd}. An @code{&assertion} condition
1046 will be raised if this field is not mutable.
1047 @end deffn
1048
1049 @node rnrs records inspection
1050 @subsubsection rnrs records inspection
1051
1052 The @code{(rnrs records inspection (6))} library provides procedures
1053 useful for accessing metadata about R6RS records.
1054
1055 @deffn {Scheme Procedure} record? obj
1056 Return @code{#t} if the specified object is a non-opaque R6RS record,
1057 @code{#f} otherwise.
1058 @end deffn
1059
1060 @deffn {Scheme Procedure} record-rtd record
1061 Returns the record-type descriptor for @var{record}. An
1062 @code{&assertion} is raised if @var{record} is opaque.
1063 @end deffn
1064
1065 @deffn {Scheme Procedure} record-type-name rtd
1066 Returns the name of the record-type descriptor @var{rtd}.
1067 @end deffn
1068
1069 @deffn {Scheme Procedure} record-type-parent rtd
1070 Returns the parent of the record-type descriptor @var{rtd}, or @code{#f}
1071 if it has none.
1072 @end deffn
1073
1074 @deffn {Scheme Procedure} record-type-uid rtd
1075 Returns the uid of the record-type descriptor @var{rtd}, or @code{#f} if
1076 it has none.
1077 @end deffn
1078
1079 @deffn {Scheme Procedure} record-type-generative? rtd
1080 Returns @code{#t} if the record-type descriptor @var{rtd} is generative,
1081 @code{#f} otherwise.
1082 @end deffn
1083
1084 @deffn {Scheme Procedure} record-type-sealed? rtd
1085 Returns @code{#t} if the record-type descriptor @var{rtd} is sealed,
1086 @code{#f} otherwise.
1087 @end deffn
1088
1089 @deffn {Scheme Procedure} record-type-opaque? rtd
1090 Returns @code{#t} if the record-type descriptor @var{rtd} is opaque,
1091 @code{#f} otherwise.
1092 @end deffn
1093
1094 @deffn {Scheme Procedure} record-type-field-names rtd
1095 Returns a vector of symbols giving the names of the fields defined by
1096 the record-type descriptor @var{rtd} (and not any of its sub- or
1097 supertypes).
1098 @end deffn
1099
1100 @deffn {Scheme Procedure} record-field-mutable? rtd k
1101 Returns @code{#t} if the field at index @var{k} of the record-type
1102 descriptor @var{rtd} (and not any of its sub- or supertypes) is mutable.
1103 @end deffn
1104
1105 @node rnrs exceptions
1106 @subsubsection rnrs exceptions
1107
1108 The @code{(rnrs exceptions (6))} library provides functionality related
1109 to signaling and handling exceptional situations. This functionality is
1110 similar to the exception handling systems provided by Guile's core
1111 library @xref{Exceptions}, and by the SRFI-18 and SRFI-34
1112 modules---@xref{SRFI-18 Exceptions}, and @ref{SRFI-34},
1113 respectively---but there are some key differences in concepts and
1114 behavior.
1115
1116 A raised exception may be @dfn{continuable} or @dfn{non-continuable}.
1117 When an exception is raised non-continuably, another exception, with the
1118 condition type @code{&non-continuable}, will be raised when the
1119 exception handler returns locally. Raising an exception continuably
1120 captures the current continuation and invokes it after a local return
1121 from the exception handler.
1122
1123 Like SRFI-18 and SRFI-34, R6RS exceptions are implemented on top of
1124 Guile's native @code{throw} and @code{catch} forms, and use custom
1125 ``throw keys'' to identify their exception types. As a consequence,
1126 Guile's @code{catch} form can handle exceptions thrown by these APIs,
1127 but the reverse is not true: Handlers registered by the
1128 @code{with-exception-handler} procedure described below will only be
1129 called on exceptions thrown by the corresponding @code{raise} procedure.
1130
1131 @deffn {Scheme Procedure} with-exception-handler handler thunk
1132 Installs @var{handler}, which must be a procedure taking one argument,
1133 as the current exception handler during the invocation of @var{thunk}, a
1134 procedure taking zero arguments. The handler in place at the time
1135 @code{with-exception-handler} is called is made current again once
1136 either @var{thunk} returns or @var{handler} is invoked after an
1137 exception is thrown from within @var{thunk}.
1138
1139 This procedure is similar to the @code{with-throw-handler} procedure
1140 provided by Guile's code library; (@pxref{Throw Handlers}).
1141 @end deffn
1142
1143 @deffn {Scheme Syntax} guard (variable clause1 clause2 ...) body
1144 Evaluates the expression given by @var{body}, first creating an ad hoc
1145 exception handler that binds a raised exception to @var{variable} and
1146 then evaluates the specified @var{clause}s as if they were part of a
1147 @code{cond} expression, with the value of the first matching clause
1148 becoming the value of the @code{guard} expression
1149 (@pxref{if cond case}). If none of the clause's test expressions
1150 evaluates to @code{#t}, the exception is re-raised, with the exception
1151 handler that was current before the evaluation of the @code{guard} form.
1152
1153 For example, the expression
1154
1155 @lisp
1156 (guard (ex ((eq? ex 'foo) 'bar) ((eq? ex 'bar) 'baz))
1157 (raise 'bar))
1158 @end lisp
1159
1160 evaluates to @code{baz}.
1161 @end deffn
1162
1163 @deffn {Scheme Procedure} raise obj
1164 Raises a non-continuable exception by invoking the currently-installed
1165 exception handler on @var{obj}. If the handler returns, a
1166 @code{&non-continuable} exception will be raised in the dynamic context
1167 in which the handler was installed.
1168 @end deffn
1169
1170 @deffn {Scheme Procedure} raise-continuable obj
1171 Raises a continuable exception by invoking currently-installed exception
1172 handler on @var{obj}.
1173 @end deffn
1174
1175 @node rnrs conditions
1176 @subsubsection rnrs conditions
1177
1178 The @code{(rnrs condition (6))} library provides forms and procedures
1179 for constructing new condition types, as well as a library of
1180 pre-defined condition types that represent a variety of common
1181 exceptional situations. Conditions are records of a subtype of the
1182 @code{&condition} record type, which is neither sealed nor opaque.
1183 @xref{R6RS Records}.
1184
1185 Conditions may be manipulated singly, as @dfn{simple conditions}, or
1186 when composed with other conditions to form @dfn{compound conditions}.
1187 Compound conditions do not ``nest''---constructing a new compound
1188 condition out of existing compound conditions will ``flatten'' them
1189 into their component simple conditions. For example, making a new
1190 condition out of a @code{&message} condition and a compound condition
1191 that contains an @code{&assertion} condition and another @code{&message}
1192 condition will produce a compound condition that contains two
1193 @code{&message} conditions and one @code{&assertion} condition.
1194
1195 The record type predicates and field accessors described below can
1196 operate on either simple or compound conditions. In the latter case,
1197 the predicate returns @code{#t} if the compound condition contains a
1198 component simple condition of the appropriate type; the field accessors
1199 return the requisite fields from the first component simple condition
1200 found to be of the appropriate type.
1201
1202 This library is quite similar to the SRFI-35 conditions module
1203 (@pxref{SRFI-35}). Among other minor differences, the
1204 @code{(rnrs conditions)} library features slightly different semantics
1205 around condition field accessors, and comes with a larger number of
1206 pre-defined condition types. The two APIs are not currently compatible,
1207 however; the @code{condition?} predicate from one API will return
1208 @code{#f} when applied to a condition object created in the other.
1209
1210 @deffn {Condition Type} &condition
1211 @deffnx {Scheme Procedure} condition? obj
1212 The base record type for conditions.
1213 @end deffn
1214
1215 @deffn {Scheme Procedure} condition condition1 ...
1216 @deffnx {Scheme Procedure} simple-conditions condition
1217 The @code{condition} procedure creates a new compound condition out of
1218 its condition arguments, flattening any specified compound conditions
1219 into their component simple conditions as described above.
1220
1221 @code{simple-conditions} returns a list of the component simple
1222 conditions of the compound condition @code{condition}, in the order in
1223 which they were specified at construction time.
1224 @end deffn
1225
1226 @deffn {Scheme Procedure} condition-predicate rtd
1227 @deffnx {Scheme Procedure} condition-accessor rtd proc
1228 These procedures return condition predicate and accessor procedures for
1229 the specified condition record type @var{rtd}.
1230 @end deffn
1231
1232 @deffn {Scheme Syntax} define-condition-type condition-type supertype constructor predicate field-spec ...
1233 Evaluates to a new record type definition for a condition type with the
1234 name @var{condition-type} that has the condition type @var{supertype} as
1235 its parent. A default constructor, which binds its arguments to the
1236 fields of this type and its parent types, will be bound to the
1237 identifier @var{constructor}; a condition predicate will be bound to
1238 @var{predicate}. The fields of the new type, which are immutable, are
1239 specified by the @var{field-spec}s, each of which must be of the form:
1240 @lisp
1241 (field accessor)
1242 @end lisp
1243 where @var{field} gives the name of the field and @var{accessor} gives
1244 the name for a binding to an accessor procedure created for this field.
1245 @end deffn
1246
1247 @deffn {Condition Type} &message
1248 @deffnx {Scheme Procedure} make-message-condition message
1249 @deffnx {Scheme Procedure} message-condition? obj
1250 @deffnx {Scheme Procedure} condition-message condition
1251 A type that includes a message describing the condition that occurred.
1252 @end deffn
1253
1254 @deffn {Condition Type} &warning
1255 @deffnx {Scheme Procedure} make-warning
1256 @deffnx {Scheme Procedure} warning? obj
1257 A base type for representing non-fatal conditions during execution.
1258 @end deffn
1259
1260 @deffn {Condition Type} &serious
1261 @deffnx {Scheme Procedure} make-serious-condition
1262 @deffnx {Scheme Procedure} serious-condition? obj
1263 A base type for conditions representing errors serious enough that
1264 cannot be ignored.
1265 @end deffn
1266
1267 @deffn {Condition Type} &error
1268 @deffnx {Scheme Procedure} make-error
1269 @deffnx {Scheme Procedure} error? obj
1270 A base type for conditions representing errors.
1271 @end deffn
1272
1273 @deffn {Condition Type} &violation
1274 @deffnx {Scheme Procedure} make-violation
1275 @deffnx {Scheme Procedure} violation?
1276 A subtype of @code{&serious} that can be used to represent violations
1277 of a language or library standard.
1278 @end deffn
1279
1280 @deffn {Condition Type} &assertion
1281 @deffnx {Scheme Procedure} make-assertion-violation
1282 @deffnx {Scheme Procedure} assertion-violation? obj
1283 A subtype of @code{&violation} that indicates an invalid call to a
1284 procedure.
1285 @end deffn
1286
1287 @deffn {Condition Type} &irritants
1288 @deffnx {Scheme Procedure} make-irritants-condition irritants
1289 @deffnx {Scheme Procedure} irritants-condition? obj
1290 @deffnx {Scheme Procedure} condition-irritants condition
1291 A base type used for storing information about the causes of another
1292 condition in a compound condition.
1293 @end deffn
1294
1295 @deffn {Condition Type} &who
1296 @deffnx {Scheme Procedure} make-who-condition who
1297 @deffnx {Scheme Procedure} who-condition? obj
1298 @deffnx {Scheme Procedure} condition-who condition
1299 A base type used for storing the identity, a string or symbol, of the
1300 entity responsible for another condition in a compound condition.
1301 @end deffn
1302
1303 @deffn {Condition Type} &non-continuable
1304 @deffnx {Scheme Procedure} make-non-continuable-violation
1305 @deffnx {Scheme Procedure} non-continuable-violation? obj
1306 A subtype of @code{&violation} used to indicate that an exception
1307 handler invoked by @code{raise} has returned locally.
1308 @end deffn
1309
1310 @deffn {Condition Type} &implementation-restriction
1311 @deffnx {Scheme Procedure} make-implementation-restriction-violation
1312 @deffnx {Scheme Procedure} implementation-restriction-violation? obj
1313 A subtype of @code{&violation} used to indicate a violation of an
1314 implementation restriction.
1315 @end deffn
1316
1317 @deffn {Condition Type} &lexical
1318 @deffnx {Scheme Procedure} make-lexical-violation
1319 @deffnx {Scheme Procedure} lexical-violation? obj
1320 A subtype of @code{&violation} used to indicate a syntax violation at
1321 the level of the datum syntax.
1322 @end deffn
1323
1324 @deffn {Condition Type} &syntax
1325 @deffnx {Scheme Procedure} make-syntax-violation form subform
1326 @deffnx {Scheme Procedure} syntax-violation? obj
1327 @deffnx {Scheme Procedure} syntax-violation-form condition
1328 @deffnx {Scheme Procedure} syntax-violation-subform condition
1329 A subtype of @code{&violation} that indicates a syntax violation. The
1330 @var{form} and @var{subform} fields, which must be datum values,
1331 indicate the syntactic form responsible for the condition.
1332 @end deffn
1333
1334 @deffn {Condition Type} &undefined
1335 @deffnx {Scheme Procedure} make-undefined-violation
1336 @deffnx {Scheme Procedure} undefined-violation? obj
1337 A subtype of @code{&violation} that indicates a reference to an unbound
1338 identifier.
1339 @end deffn
1340
1341 @node I/O Conditions
1342 @subsubsection I/O Conditions
1343
1344 These condition types are exported by both the
1345 @code{(rnrs io ports (6))} and @code{(rnrs io simple (6))} libraries.
1346
1347 @deffn {Condition Type} &i/o
1348 @deffnx {Scheme Procedure} make-i/o-error
1349 @deffnx {Scheme Procedure} i/o-error? obj
1350 A condition supertype for more specific I/O errors.
1351 @end deffn
1352
1353 @deffn {Condition Type} &i/o-read
1354 @deffnx {Scheme Procedure} make-i/o-read-error
1355 @deffnx {Scheme Procedure} i/o-read-error? obj
1356 A subtype of @code{&i/o}; represents read-related I/O errors.
1357 @end deffn
1358
1359 @deffn {Condition Type} &i/o-write
1360 @deffnx {Scheme Procedure} make-i/o-write-error
1361 @deffnx {Scheme Procedure} i/o-write-error? obj
1362 A subtype of @code{&i/o}; represents write-related I/O errors.
1363 @end deffn
1364
1365 @deffn {Condition Type} &i/o-invalid-position
1366 @deffnx {Scheme Procedure} make-i/o-invalid-position-error position
1367 @deffnx {Scheme Procedure} i/o-invalid-position-error? obj
1368 @deffnx {Scheme Procedure} i/o-error-position condition
1369 A subtype of @code{&i/o}; represents an error related to an attempt to
1370 set the file position to an invalid position.
1371 @end deffn
1372
1373 @deffn {Condition Type} &i/o-filename
1374 @deffnx {Scheme Procedure} make-io-filename-error filename
1375 @deffnx {Scheme Procedure} i/o-filename-error? obj
1376 @deffnx {Scheme Procedure} i/o-error-filename condition
1377 A subtype of @code{&i/o}; represents an error related to an operation on
1378 a named file.
1379 @end deffn
1380
1381 @deffn {Condition Type} &i/o-file-protection
1382 @deffnx {Scheme Procedure} make-i/o-file-protection-error filename
1383 @deffnx {Scheme Procedure} i/o-file-protection-error? obj
1384 A subtype of @code{&i/o-filename}; represents an error resulting from an
1385 attempt to access a named file for which the caller had insufficient
1386 permissions.
1387 @end deffn
1388
1389 @deffn {Condition Type} &i/o-file-is-read-only
1390 @deffnx {Scheme Procedure} make-i/o-file-is-read-only-error filename
1391 @deffnx {Scheme Procedure} i/o-file-is-read-only-error? obj
1392 A subtype of @code{&i/o-file-protection}; represents an error related to
1393 an attempt to write to a read-only file.
1394 @end deffn
1395
1396 @deffn {Condition Type} &i/o-file-already-exists
1397 @deffnx {Scheme Procedure} make-i/o-file-already-exists-error filename
1398 @deffnx {Scheme Procedure} i/o-file-already-exists-error? obj
1399 A subtype of @code{&i/o-filename}; represents an error related to an
1400 operation on an existing file that was assumed not to exist.
1401 @end deffn
1402
1403 @deffn {Condition Type} &i/o-file-does-not-exist
1404 @deffnx {Scheme Procedure} make-i/o-file-does-not-exist-error
1405 @deffnx {Scheme Procedure} i/o-file-does-not-exist-error? obj
1406 A subtype of @code{&i/o-filename}; represents an error related to an
1407 operation on a non-existent file that was assumed to exist.
1408 @end deffn
1409
1410 @deffn {Condition Type} &i/o-port
1411 @deffnx {Scheme Procedure} make-i/o-port-error port
1412 @deffnx {Scheme Procedure} i/o-port-error? obj
1413 @deffnx {Scheme Procedure} i/o-error-port condition
1414 A subtype of @code{&i/o}; represents an error related to an operation on
1415 the port @var{port}.
1416 @end deffn
1417
1418 @node rnrs io ports
1419 @subsubsection rnrs io ports
1420
1421 The @code{(rnrs io ports (6))} library provides various procedures and
1422 syntactic forms for use in writing to and reading from ports. This
1423 functionality is documented in its own section of the manual;
1424 (@pxref{R6RS I/O Ports}).
1425
1426 @node rnrs io simple
1427 @subsubsection rnrs io simple
1428
1429 The @code{(rnrs io simple (6))} library provides convenience functions
1430 for performing textual I/O on ports. This library also exports all of
1431 the condition types and associated procedures described in (@pxref{I/O
1432 Conditions}). In the context of this section, when stating that a
1433 procedure behaves ``identically'' to the corresponding procedure in
1434 Guile's core library, this is modulo the behavior wrt. conditions: such
1435 procedures raise the appropriate R6RS conditions in case of error, but
1436 otherwise behave identically.
1437
1438 @c FIXME: remove the following note when proper condition behavior has
1439 @c been verified.
1440
1441 @quotation Note
1442 There are still known issues regarding condition-correctness; some
1443 errors may still be thrown as native Guile exceptions instead of the
1444 appropriate R6RS conditions.
1445 @end quotation
1446
1447 @deffn {Scheme Procedure} eof-object
1448 @deffnx {Scheme Procedure} eof-object? obj
1449 These procedures are identical to the ones provided by the
1450 @code{(rnrs io ports (6))} library. @xref{R6RS I/O Ports}, for
1451 documentation.
1452 @end deffn
1453
1454 @deffn {Scheme Procedure} input-port? obj
1455 @deffnx {Scheme Procedure} output-port? obj
1456 These procedures are identical to the ones provided by Guile's core
1457 library. @xref{Ports}, for documentation.
1458 @end deffn
1459
1460 @deffn {Scheme Procedure} call-with-input-file filename proc
1461 @deffnx {Scheme Procedure} call-with-output-file filename proc
1462 @deffnx {Scheme Procedure} open-input-file filename
1463 @deffnx {Scheme Procedure} open-output-file filename
1464 @deffnx {Scheme Procedure} with-input-from-file filename thunk
1465 @deffnx {Scheme Procedure} with-output-to-file filename thunk
1466 These procedures are identical to the ones provided by Guile's core
1467 library. @xref{File Ports}, for documentation.
1468 @end deffn
1469
1470 @deffn {Scheme Procedure} close-input-port input-port
1471 @deffnx {Scheme Procedure} close-output-port output-port
1472 These procedures are identical to the ones provided by Guile's core
1473 library. @xref{Closing}, for documentation.
1474 @end deffn
1475
1476 @deffn {Scheme Procedure} peek-char
1477 @deffnx {Scheme Procedure} peek-char textual-input-port
1478 @deffnx {Scheme Procedure} read-char
1479 @deffnx {Scheme Procedure} read-char textual-input-port
1480 These procedures are identical to the ones provided by Guile's core
1481 library. @xref{Reading}, for documentation.
1482 @end deffn
1483
1484 @deffn {Scheme Procedure} read
1485 @deffnx {Scheme Procedure} read textual-input-port
1486 This procedure is identical to the one provided by Guile's core library.
1487 @xref{Scheme Read}, for documentation.
1488 @end deffn
1489
1490 @deffn {Scheme Procedure} display obj
1491 @deffnx {Scheme Procedure} display obj textual-output-port
1492 @deffnx {Scheme Procedure} newline
1493 @deffnx {Scheme Procedure} newline textual-output-port
1494 @deffnx {Scheme Procedure} write obj
1495 @deffnx {Scheme Procedure} write obj textual-output-port
1496 @deffnx {Scheme Procedure} write-char char
1497 @deffnx {Scheme Procedure} write-char char textual-output-port
1498 These procedures are identical to the ones provided by Guile's core
1499 library. @xref{Writing}, for documentation.
1500 @end deffn
1501
1502 @node rnrs files
1503 @subsubsection rnrs files
1504
1505 The @code{(rnrs files (6))} library provides the @code{file-exists?} and
1506 @code{delete-file} procedures, which test for the existence of a file
1507 and allow the deletion of files from the file system, respectively.
1508
1509 These procedures are identical to the ones provided by Guile's core
1510 library. @xref{File System}, for documentation.
1511
1512 @node rnrs programs
1513 @subsubsection rnrs programs
1514
1515 The @code{(rnrs programs (6))} library provides procedures for
1516 process management and introspection.
1517
1518 @deffn {Scheme Procedure} command-line
1519 This procedure is identical to the one provided by Guile's core library.
1520 @xref{Runtime Environment}, for documentation.
1521 @end deffn
1522
1523 @deffn {Scheme Procedure} exit
1524 @deffnx {Scheme Procedure} exit obj
1525 This procedure is identical to the one provided by Guile's core library.
1526 @end deffn
1527
1528 @node rnrs arithmetic fixnums
1529 @subsubsection rnrs arithmetic fixnums
1530
1531 The @code{(rnrs arithmetic fixnums (6))} library provides procedures for
1532 performing arithmetic operations on an implementation-dependent range of
1533 exact integer values, which R6RS refers to as @dfn{fixnums}. In Guile,
1534 the size of a fixnum is determined by the size of the @code{SCM} type; a
1535 single SCM struct is guaranteed to be able to hold an entire fixnum,
1536 making fixnum computations particularly
1537 efficient---(@pxref{The SCM Type}). On 32-bit systems, the most
1538 negative and most positive fixnum values are, respectively, -536870912
1539 and 536870911.
1540
1541 Unless otherwise specified, all of the procedures below take fixnums as
1542 arguments, and will raise an @code{&assertion} condition if passed a
1543 non-fixnum argument or an @code{&implementation-restriction} condition
1544 if their result is not itself a fixnum.
1545
1546 @deffn {Scheme Procedure} fixnum? obj
1547 Returns @code{#t} if @var{obj} is a fixnum, @code{#f} otherwise.
1548 @end deffn
1549
1550 @deffn {Scheme Procedure} fixnum-width
1551 @deffnx {Scheme Procedure} least-fixnum
1552 @deffnx {Scheme Procedure} greatest-fixnum
1553 These procedures return, respectively, the maximum number of bits
1554 necessary to represent a fixnum value in Guile, the minimum fixnum
1555 value, and the maximum fixnum value.
1556 @end deffn
1557
1558 @deffn {Scheme Procedure} fx=? fx1 fx2 fx3 ...
1559 @deffnx {Scheme Procedure} fx>? fx1 fx2 fx3 ...
1560 @deffnx {Scheme Procedure} fx<? fx1 fx2 fx3 ...
1561 @deffnx {Scheme Procedure} fx>=? fx1 fx2 fx3 ...
1562 @deffnx {Scheme Procedure} fx<=? fx1 fx2 fx3 ...
1563 These procedures return @code{#t} if their fixnum arguments are
1564 (respectively): equal, monotonically increasing, monotonically
1565 decreasing, monotonically nondecreasing, or monotonically nonincreasing;
1566 @code{#f} otherwise.
1567 @end deffn
1568
1569 @deffn {Scheme Procedure} fxzero? fx
1570 @deffnx {Scheme Procedure} fxpositive? fx
1571 @deffnx {Scheme Procedure} fxnegative? fx
1572 @deffnx {Scheme Procedure} fxodd? fx
1573 @deffnx {Scheme Procedure} fxeven? fx
1574 These numerical predicates return @code{#t} if @var{fx} is,
1575 respectively, zero, greater than zero, less than zero, odd, or even;
1576 @code{#f} otherwise.
1577 @end deffn
1578
1579 @deffn {Scheme Procedure} fxmax fx1 fx2 ...
1580 @deffnx {Scheme Procedure} fxmin fx1 fx2 ...
1581 These procedures return the maximum or minimum of their arguments.
1582 @end deffn
1583
1584 @deffn {Scheme Procedure} fx+ fx1 fx2
1585 @deffnx {Scheme Procedure} fx* fx1 fx2
1586 These procedures return the sum or product of their arguments.
1587 @end deffn
1588
1589 @deffn {Scheme Procedure} fx- fx1 fx2
1590 @deffnx {Scheme Procedure} fx- fx
1591 Returns the difference of @var{fx1} and @var{fx2}, or the negation of
1592 @var{fx}, if called with a single argument.
1593
1594 An @code{&assertion} condition is raised if the result is not itself a
1595 fixnum.
1596 @end deffn
1597
1598 @deffn {Scheme Procedure} fxdiv-and-mod fx1 fx2
1599 @deffnx {Scheme Procedure} fxdiv fx1 fx2
1600 @deffnx {Scheme Procedure} fxmod fx1 fx2
1601 @deffnx {Scheme Procedure} fxdiv0-and-mod0 fx1 fx2
1602 @deffnx {Scheme Procedure} fxdiv0 fx1 fx2
1603 @deffnx {Scheme Procedure} fxmod0 fx1 fx2
1604 These procedures implement number-theoretic division on fixnums;
1605 @xref{(rnrs base)}, for a description of their semantics.
1606 @end deffn
1607
1608 @deffn {Scheme Procedure} fx+/carry fx1 fx2 fx3
1609 Returns the two fixnum results of the following computation:
1610 @lisp
1611 (let* ((s (+ fx1 fx2 fx3))
1612 (s0 (mod0 s (expt 2 (fixnum-width))))
1613 (s1 (div0 s (expt 2 (fixnum-width)))))
1614 (values s0 s1))
1615 @end lisp
1616 @end deffn
1617
1618 @deffn {Scheme Procedure} fx-/carry fx1 fx2 fx3
1619 Returns the two fixnum results of the following computation:
1620 @lisp
1621 (let* ((d (- fx1 fx2 fx3))
1622 (d0 (mod0 d (expt 2 (fixnum-width))))
1623 (d1 (div0 d (expt 2 (fixnum-width)))))
1624 (values d0 d1))
1625 @end lisp
1626 @end deffn
1627
1628 @deffn {Scheme Procedure} fx*/carry fx1 fx2 fx3
1629 @lisp
1630 Returns the two fixnum results of the following computation:
1631 (let* ((s (+ (* fx1 fx2) fx3))
1632 (s0 (mod0 s (expt 2 (fixnum-width))))
1633 (s1 (div0 s (expt 2 (fixnum-width)))))
1634 (values s0 s1))
1635 @end lisp
1636 @end deffn
1637
1638 @deffn {Scheme Procedure} fxnot fx
1639 @deffnx {Scheme Procedure} fxand fx1 ...
1640 @deffnx {Scheme Procedure} fxior fx1 ...
1641 @deffnx {Scheme Procedure} fxxor fx1 ...
1642 These procedures are identical to the @code{lognot}, @code{logand},
1643 @code{logior}, and @code{logxor} procedures provided by Guile's core
1644 library. @xref{Bitwise Operations}, for documentation.
1645 @end deffn
1646
1647 @deffn {Scheme Procedure} fxif fx1 fx2 fx3
1648 Returns the bitwise ``if'' of its fixnum arguments. The bit at position
1649 @code{i} in the return value will be the @code{i}th bit from @var{fx2}
1650 if the @code{i}th bit of @var{fx1} is 1, the @code{i}th bit from
1651 @var{fx3}.
1652 @end deffn
1653
1654 @deffn {Scheme Procedure} fxbit-count fx
1655 Returns the number of 1 bits in the two's complement representation of
1656 @var{fx}.
1657 @end deffn
1658
1659 @deffn {Scheme Procedure} fxlength fx
1660 Returns the number of bits necessary to represent @var{fx}.
1661 @end deffn
1662
1663 @deffn {Scheme Procedure} fxfirst-bit-set fx
1664 Returns the index of the least significant 1 bit in the two's complement
1665 representation of @var{fx}.
1666 @end deffn
1667
1668 @deffn {Scheme Procedure} fxbit-set? fx1 fx2
1669 Returns @code{#t} if the @var{fx2}th bit in the two's complement
1670 representation of @var{fx1} is 1, @code{#f} otherwise.
1671 @end deffn
1672
1673 @deffn {Scheme Procedure} fxcopy-bit fx1 fx2 fx3
1674 Returns the result of setting the @var{fx2}th bit of @var{fx1} to the
1675 @var{fx2}th bit of @var{fx3}.
1676 @end deffn
1677
1678 @deffn {Scheme Procedure} fxbit-field fx1 fx2 fx3
1679 Returns the integer representation of the contiguous sequence of bits in
1680 @var{fx1} that starts at position @var{fx2} (inclusive) and ends at
1681 position @var{fx3} (exclusive).
1682 @end deffn
1683
1684 @deffn {Scheme Procedure} fxcopy-bit-field fx1 fx2 fx3 fx4
1685 Returns the result of replacing the bit field in @var{fx1} with start
1686 and end positions @var{fx2} and @var{fx3} with the corresponding bit
1687 field from @var{fx4}.
1688 @end deffn
1689
1690 @deffn {Scheme Procedure} fxarithmetic-shift fx1 fx2
1691 @deffnx {Scheme Procedure} fxarithmetic-shift-left fx1 fx2
1692 @deffnx {Scheme Procedure} fxarithmetic-shift-right fx1 fx2
1693 Returns the result of shifting the bits of @var{fx1} right or left by
1694 the @var{fx2} positions. @code{fxarithmetic-shift} is identical
1695 to @code{fxarithmetic-shift-left}.
1696 @end deffn
1697
1698 @deffn {Scheme Procedure} fxrotate-bit-field fx1 fx2 fx3 fx4
1699 Returns the result of cyclically permuting the bit field in @var{fx1}
1700 with start and end positions @var{fx2} and @var{fx3} by @var{fx4} bits
1701 in the direction of more significant bits.
1702 @end deffn
1703
1704 @deffn {Scheme Procedure} fxreverse-bit-field fx1 fx2 fx3
1705 Returns the result of reversing the order of the bits of @var{fx1}
1706 between position @var{fx2} (inclusive) and position @var{fx3}
1707 (exclusive).
1708 @end deffn
1709
1710 @node rnrs arithmetic flonums
1711 @subsubsection rnrs arithmetic flonums
1712
1713 The @code{(rnrs arithmetic flonums (6))} library provides procedures for
1714 performing arithmetic operations on inexact representations of real
1715 numbers, which R6RS refers to as @dfn{flonums}.
1716
1717 Unless otherwise specified, all of the procedures below take flonums as
1718 arguments, and will raise an @code{&assertion} condition if passed a
1719 non-flonum argument.
1720
1721 @deffn {Scheme Procedure} flonum? obj
1722 Returns @code{#t} if @var{obj} is a flonum, @code{#f} otherwise.
1723 @end deffn
1724
1725 @deffn {Scheme Procedure} real->flonum x
1726 Returns the flonum that is numerically closest to the real number
1727 @var{x}.
1728 @end deffn
1729
1730 @deffn {Scheme Procedure} fl=? fl1 fl2 fl3 ...
1731 @deffnx {Scheme Procedure} fl<? fl1 fl2 fl3 ...
1732 @deffnx {Scheme Procedure} fl<=? fl1 fl2 fl3 ...
1733 @deffnx {Scheme Procedure} fl>? fl1 fl2 fl3 ...
1734 @deffnx {Scheme Procedure} fl>=? fl1 fl2 fl3 ...
1735 These procedures return @code{#t} if their flonum arguments are
1736 (respectively): equal, monotonically increasing, monotonically
1737 decreasing, monotonically nondecreasing, or monotonically nonincreasing;
1738 @code{#f} otherwise.
1739 @end deffn
1740
1741 @deffn {Scheme Procedure} flinteger? fl
1742 @deffnx {Scheme Procedure} flzero? fl
1743 @deffnx {Scheme Procedure} flpositive? fl
1744 @deffnx {Scheme Procedure} flnegative? fl
1745 @deffnx {Scheme Procedure} flodd? fl
1746 @deffnx {Scheme Procedure} fleven? fl
1747 These numerical predicates return @code{#t} if @var{fl} is,
1748 respectively, an integer, zero, greater than zero, less than zero, odd,
1749 even, @code{#f} otherwise. In the case of @code{flodd?} and
1750 @code{fleven?}, @var{fl} must be an integer-valued flonum.
1751 @end deffn
1752
1753 @deffn {Scheme Procedure} flfinite? fl
1754 @deffnx {Scheme Procedure} flinfinite? fl
1755 @deffnx {Scheme Procedure} flnan? fl
1756 These numerical predicates return @code{#t} if @var{fl} is,
1757 respectively, not infinite, infinite, or a @code{NaN} value.
1758 @end deffn
1759
1760 @deffn {Scheme Procedure} flmax fl1 fl2 ...
1761 @deffnx {Scheme Procedure} flmin fl1 fl2 ...
1762 These procedures return the maximum or minimum of their arguments.
1763 @end deffn
1764
1765 @deffn {Scheme Procedure} fl+ fl1 ...
1766 @deffnx {Scheme Procedure} fl* fl ...
1767 These procedures return the sum or product of their arguments.
1768 @end deffn
1769
1770 @deffn {Scheme Procedure} fl- fl1 fl2 ...
1771 @deffnx {Scheme Procedure} fl- fl
1772 @deffnx {Scheme Procedure} fl/ fl1 fl2 ...
1773 @deffnx {Scheme Procedure} fl/ fl
1774 These procedures return, respectively, the difference or quotient of
1775 their arguments when called with two arguments; when called with a
1776 single argument, they return the additive or multiplicative inverse of
1777 @var{fl}.
1778 @end deffn
1779
1780 @deffn {Scheme Procedure} flabs fl
1781 Returns the absolute value of @var{fl}.
1782 @end deffn
1783
1784 @deffn {Scheme Procedure} fldiv-and-mod fl1 fl2
1785 @deffnx {Scheme Procedure} fldiv fl1 fl2
1786 @deffnx {Scheme Procedure} fldmod fl1 fl2
1787 @deffnx {Scheme Procedure} fldiv0-and-mod0 fl1 fl2
1788 @deffnx {Scheme Procedure} fldiv0 fl1 fl2
1789 @deffnx {Scheme Procedure} flmod0 fl1 fl2
1790 These procedures implement number-theoretic division on flonums;
1791 @xref{(rnrs base)}, for a description for their semantics.
1792 @end deffn
1793
1794 @deffn {Scheme Procedure} flnumerator fl
1795 @deffnx {Scheme Procedure} fldenominator fl
1796 These procedures return the numerator or denominator of @var{fl} as a
1797 flonum.
1798 @end deffn
1799
1800 @deffn {Scheme Procedure} flfloor fl1
1801 @deffnx {Scheme Procedure} flceiling fl
1802 @deffnx {Scheme Procedure} fltruncate fl
1803 @deffnx {Scheme Procedure} flround fl
1804 These procedures are identical to the @code{floor}, @code{ceiling},
1805 @code{truncate}, and @code{round} procedures provided by Guile's core
1806 library. @xref{Arithmetic}, for documentation.
1807 @end deffn
1808
1809 @deffn {Scheme Procedure} flexp fl
1810 @deffnx {Scheme Procedure} fllog fl
1811 @deffnx {Scheme Procedure} fllog fl1 fl2
1812 @deffnx {Scheme Procedure} flsin fl
1813 @deffnx {Scheme Procedure} flcos fl
1814 @deffnx {Scheme Procedure} fltan fl
1815 @deffnx {Scheme Procedure} flasin fl
1816 @deffnx {Scheme Procedure} flacos fl
1817 @deffnx {Scheme Procedure} flatan fl
1818 @deffnx {Scheme Procedure} flatan fl1 fl2
1819 These procedures, which compute the usual transcendental functions, are
1820 the flonum variants of the procedures provided by the R6RS base library
1821 (@pxref{(rnrs base)}).
1822 @end deffn
1823
1824 @deffn {Scheme Procedure} flsqrt fl
1825 Returns the square root of @var{fl}. If @var{fl} is @code{-0.0},
1826 @var{-0.0} is returned; for other negative values, a @code{NaN} value
1827 is returned.
1828 @end deffn
1829
1830 @deffn {Scheme Procedure} flexpt fl1 fl2
1831 Returns the value of @var{fl1} raised to the power of @var{fl2}.
1832 @end deffn
1833
1834 The following condition types are provided to allow Scheme
1835 implementations that do not support infinities or @code{NaN} values
1836 to indicate that a computation resulted in such a value. Guile supports
1837 both of these, so these conditions will never be raised by Guile's
1838 standard libraries implementation.
1839
1840 @deffn {Condition Type} &no-infinities
1841 @deffnx {Scheme Procedure} make-no-infinities-violation obj
1842 @deffnx {Scheme Procedure} no-infinities-violation?
1843 A condition type indicating that a computation resulted in an infinite
1844 value on a Scheme implementation incapable of representing infinities.
1845 @end deffn
1846
1847 @deffn {Condition Type} &no-nans
1848 @deffnx {Scheme Procedure} make-no-nans-violation obj
1849 @deffnx {Scheme Procedure} no-nans-violation? obj
1850 A condition type indicating that a computation resulted in a @code{NaN}
1851 value on a Scheme implementation incapable of representing @code{NaN}s.
1852 @end deffn
1853
1854 @deffn {Scheme Procedure} fixnum->flonum fx
1855 Returns the flonum that is numerically closest to the fixnum @var{fx}.
1856 @end deffn
1857
1858 @node rnrs arithmetic bitwise
1859 @subsubsection rnrs arithmetic bitwise
1860
1861 The @code{(rnrs arithmetic bitwise (6))} library provides procedures for
1862 performing bitwise arithmetic operations on the two's complement
1863 representations of fixnums.
1864
1865 This library and the procedures it exports share functionality with
1866 SRFI-60, which provides support for bitwise manipulation of integers
1867 (@pxref{SRFI-60}).
1868
1869 @deffn {Scheme Procedure} bitwise-not ei
1870 @deffnx {Scheme Procedure} bitwise-and ei1 ...
1871 @deffnx {Scheme Procedure} bitwise-ior ei1 ...
1872 @deffnx {Scheme Procedure} bitwise-xor ei1 ...
1873 These procedures are identical to the @code{lognot}, @code{logand},
1874 @code{logior}, and @code{logxor} procedures provided by Guile's core
1875 library. @xref{Bitwise Operations}, for documentation.
1876 @end deffn
1877
1878 @deffn {Scheme Procedure} bitwise-if ei1 ei2 ei3
1879 Returns the bitwise ``if'' of its arguments. The bit at position
1880 @code{i} in the return value will be the @code{i}th bit from @var{ei2}
1881 if the @code{i}th bit of @var{ei1} is 1, the @code{i}th bit from
1882 @var{ei3}.
1883 @end deffn
1884
1885 @deffn {Scheme Procedure} bitwise-bit-count ei
1886 Returns the number of 1 bits in the two's complement representation of
1887 @var{ei}.
1888 @end deffn
1889
1890 @deffn {Scheme Procedure} bitwise-length ei
1891 Returns the number of bits necessary to represent @var{ei}.
1892 @end deffn
1893
1894 @deffn {Scheme Procedure} bitwise-first-bit-set ei
1895 Returns the index of the least significant 1 bit in the two's complement
1896 representation of @var{ei}.
1897 @end deffn
1898
1899 @deffn {Scheme Procedure} bitwise-bit-set? ei1 ei2
1900 Returns @code{#t} if the @var{ei2}th bit in the two's complement
1901 representation of @var{ei1} is 1, @code{#f} otherwise.
1902 @end deffn
1903
1904 @deffn {Scheme Procedure} bitwise-copy-bit ei1 ei2 ei3
1905 Returns the result of setting the @var{ei2}th bit of @var{ei1} to the
1906 @var{ei2}th bit of @var{ei3}.
1907 @end deffn
1908
1909 @deffn {Scheme Procedure} bitwise-bit-field ei1 ei2 ei3
1910 Returns the integer representation of the contiguous sequence of bits in
1911 @var{ei1} that starts at position @var{ei2} (inclusive) and ends at
1912 position @var{ei3} (exclusive).
1913 @end deffn
1914
1915 @deffn {Scheme Procedure} bitwise-copy-bit-field ei1 ei2 ei3 ei4
1916 Returns the result of replacing the bit field in @var{ei1} with start
1917 and end positions @var{ei2} and @var{ei3} with the corresponding bit
1918 field from @var{ei4}.
1919 @end deffn
1920
1921 @deffn {Scheme Procedure} bitwise-arithmetic-shift ei1 ei2
1922 @deffnx {Scheme Procedure} bitwise-arithmetic-shift-left ei1 ei2
1923 @deffnx {Scheme Procedure} bitwise-arithmetic-shift-right ei1 ei2
1924 Returns the result of shifting the bits of @var{ei1} right or left by
1925 the @var{ei2} positions. @code{bitwise-arithmetic-shift} is identical
1926 to @code{bitwise-arithmetic-shift-left}.
1927 @end deffn
1928
1929 @deffn {Scheme Procedure} bitwise-rotate-bit-field ei1 ei2 ei3 ei4
1930 Returns the result of cyclically permuting the bit field in @var{ei1}
1931 with start and end positions @var{ei2} and @var{ei3} by @var{ei4} bits
1932 in the direction of more significant bits.
1933 @end deffn
1934
1935 @deffn {Scheme Procedure} bitwise-reverse-bit-field ei1 ei2 ei3
1936 Returns the result of reversing the order of the bits of @var{ei1}
1937 between position @var{ei2} (inclusive) and position @var{ei3}
1938 (exclusive).
1939 @end deffn
1940
1941 @node rnrs syntax-case
1942 @subsubsection rnrs syntax-case
1943
1944 The @code{(rnrs syntax-case (6))} library provides access to the
1945 @code{syntax-case} system for writing hygienic macros. With one
1946 exception, all of the forms and procedures exported by this library
1947 are ``re-exports'' of Guile's native support for @code{syntax-case};
1948 @xref{Syntax Case}, for documentation, examples, and rationale.
1949
1950 @deffn {Scheme Procedure} make-variable-transformer proc
1951 Creates a new variable transformer out of @var{proc}, a procedure that
1952 takes a syntax object as input and returns a syntax object. If an
1953 identifier to which the result of this procedure is bound appears on the
1954 left-hand side of a @code{set!} expression, @var{proc} will be called
1955 with a syntax object representing the entire @code{set!} expression,
1956 and its return value will replace that @code{set!} expression.
1957 @end deffn
1958
1959 @deffn {Scheme Syntax} syntax-case expression (literal ...) clause ...
1960 The @code{syntax-case} pattern matching form.
1961 @end deffn
1962
1963 @deffn {Scheme Syntax} syntax template
1964 @deffnx {Scheme Syntax} quasisyntax template
1965 @deffnx {Scheme Syntax} unsyntax template
1966 @deffnx {Scheme Syntax} unsyntax-splicing template
1967 These forms allow references to be made in the body of a syntax-case
1968 output expression subform to datum and non-datum values. They are
1969 identical to the forms provided by Guile's core library;
1970 @xref{Syntax Case}, for documentation.
1971 @end deffn
1972
1973 @deffn {Scheme Procedure} identifier? obj
1974 @deffnx {Scheme Procedure} bound-identifier=? id1 id2
1975 @deffnx {Scheme Procedure} free-identifier=? id1 id2
1976 These predicate procedures operate on syntax objects representing
1977 Scheme identifiers. @code{identifier?} returns @code{#t} if @var{obj}
1978 represents an identifier, @code{#f} otherwise.
1979 @code{bound-identifier=?} returns @code{#t} if and only if a binding for
1980 @var{id1} would capture a reference to @var{id2} in the transformer's
1981 output, or vice-versa. @code{free-identifier=?} returns @code{#t} if
1982 and only @var{id1} and @var{id2} would refer to the same binding in the
1983 output of the transformer, independent of any bindings introduced by the
1984 transformer.
1985 @end deffn
1986
1987 @deffn {Scheme Procedure} generate-temporaries l
1988 Returns a list, of the same length as @var{l}, which must be a list or
1989 a syntax object representing a list, of globally unique symbols.
1990 @end deffn
1991
1992 @deffn {Scheme Procedure} syntax->datum syntax-object
1993 @deffnx {Scheme Procedure} datum->syntax template-id datum
1994 These procedures convert wrapped syntax objects to and from Scheme datum
1995 values. The syntax object returned by @code{datum->syntax} shares
1996 contextual information with the syntax object @var{template-id}.
1997 @end deffn
1998
1999 @deffn {Scheme Procedure} syntax-violation whom message form
2000 @deffnx {Scheme Procedure} syntax-violation whom message form subform
2001 Constructs a new compound condition that includes the following
2002 simple conditions:
2003 @itemize @bullet
2004 @item
2005 If @var{whom} is not @code{#f}, a @code{&who} condition with the
2006 @var{whom} as its field
2007 @item
2008 A @code{&message} condition with the specified @var{message}
2009 @item
2010 A @code{&syntax} condition with the specified @var{form} and optional
2011 @var{subform} fields
2012 @end itemize
2013 @end deffn
2014
2015 @node rnrs hashtables
2016 @subsubsection rnrs hashtables
2017
2018 The @code{(rnrs hashtables (6))} library provides structures and
2019 procedures for creating and accessing hash tables. The hash tables API
2020 defined by R6RS is substantially similar to both Guile's native hash
2021 tables implementation as well as the one provided by SRFI-69;
2022 @xref{Hash Tables}, and @ref{SRFI-69}, respectively. Note that you can
2023 write portable R6RS library code that manipulates SRFI-69 hash tables
2024 (by importing the @code{(srfi :69)} library); however, hash tables
2025 created by one API cannot be used by another.
2026
2027 Like SRFI-69 hash tables---and unlike Guile's native ones---R6RS hash
2028 tables associate hash and equality functions with a hash table at the
2029 time of its creation. Additionally, R6RS allows for the creation
2030 (via @code{hashtable-copy}; see below) of immutable hash tables.
2031
2032 @deffn {Scheme Procedure} make-eq-hashtable
2033 @deffnx {Scheme Procedure} make-eq-hashtable k
2034 Returns a new hash table that uses @code{eq?} to compare keys and
2035 Guile's @code{hashq} procedure as a hash function. If @var{k} is given,
2036 it specifies the initial capacity of the hash table.
2037 @end deffn
2038
2039 @deffn {Scheme Procedure} make-eqv-hashtable
2040 @deffnx {Scheme Procedure} make-eqv-hashtable k
2041 Returns a new hash table that uses @code{eqv?} to compare keys and
2042 Guile's @code{hashv} procedure as a hash function. If @var{k} is given,
2043 it specifies the initial capacity of the hash table.
2044 @end deffn
2045
2046 @deffn {Scheme Procedure} make-hashtable hash-function equiv
2047 @deffnx {Scheme Procedure} make-hashtable hash-function equiv k
2048 Returns a new hash table that uses @var{equiv} to compare keys and
2049 @var{hash-function} as a hash function. @var{equiv} must be a procedure
2050 that accepts two arguments and returns a true value if they are
2051 equivalent, @code{#f} otherwise; @var{hash-function} must be a procedure
2052 that accepts one argument and returns a non-negative integer.
2053
2054 If @var{k} is given, it specifies the initial capacity of the hash
2055 table.
2056 @end deffn
2057
2058 @deffn {Scheme Procedure} hashtable? obj
2059 Returns @code{#t} if @var{obj} is an R6RS hash table, @code{#f}
2060 otherwise.
2061 @end deffn
2062
2063 @deffn {Scheme Procedure} hashtable-size hashtable
2064 Returns the number of keys currently in the hash table @var{hashtable}.
2065 @end deffn
2066
2067 @deffn {Scheme Procedure} hashtable-ref hashtable key default
2068 Returns the value associated with @var{key} in the hash table
2069 @var{hashtable}, or @var{default} if none is found.
2070 @end deffn
2071
2072 @deffn {Scheme Procedure} hashtable-set! hashtable key obj
2073 Associates the key @var{key} with the value @var{obj} in the hash table
2074 @var{hashtable}, and returns an unspecified value. An @code{&assertion}
2075 condition is raised if @var{hashtable} is immutable.
2076 @end deffn
2077
2078 @deffn {Scheme Procedure} hashtable-delete! hashtable key
2079 Removes any association found for the key @var{key} in the hash table
2080 @var{hashtable}, and returns an unspecified value. An @code{&assertion}
2081 condition is raised if @var{hashtable} is immutable.
2082 @end deffn
2083
2084 @deffn {Scheme Procedure} hashtable-contains? hashtable key
2085 Returns @code{#t} if the hash table @var{hashtable} contains an
2086 association for the key @var{key}, @code{#f} otherwise.
2087 @end deffn
2088
2089 @deffn {Scheme Procedure} hashtable-update! hashtable key proc default
2090 Associates with @var{key} in the hash table @var{hashtable} the result
2091 of calling @var{proc}, which must be a procedure that takes one
2092 argument, on the value currently associated @var{key} in
2093 @var{hashtable}---or on @var{default} if no such association exists.
2094 An @code{&assertion} condition is raised if @var{hashtable} is
2095 immutable.
2096 @end deffn
2097
2098 @deffn {Scheme Procedure} hashtable-copy hashtable
2099 @deffnx {Scheme Procedure} hashtable-copy hashtable mutable
2100 Returns a copy of the hash table @var{hashtable}. If the optional
2101 argument @var{mutable} is a true value, the new hash table will be
2102 immutable.
2103 @end deffn
2104
2105 @deffn {Scheme Procedure} hashtable-clear! hashtable
2106 @deffnx {Scheme Procedure} hashtable-clear! hashtable k
2107 Removes all of the associations from the hash table @var{hashtable}.
2108 The optional argument @var{k}, which specifies a new capacity for the
2109 hash table, is accepted by Guile's @code{(rnrs hashtables)}
2110 implementation, but is ignored.
2111 @end deffn
2112
2113 @deffn {Scheme Procedure} hashtable-keys hashtable
2114 Returns a vector of the keys with associations in the hash table
2115 @var{hashtable}, in an unspecified order.
2116 @end deffn
2117
2118 @deffn {Scheme Procedure} hashtable-entries hashtable
2119 Return two values---a vector of the keys with associations in the hash
2120 table @var{hashtable}, and a vector of the values to which these keys
2121 are mapped, in corresponding but unspecified order.
2122 @end deffn
2123
2124 @deffn {Scheme Procedure} hashtable-equivalence-function hashtable
2125 Returns the equivalence predicated use by @var{hashtable}. This
2126 procedure returns @code{eq?} and @code{eqv?}, respectively, for hash
2127 tables created by @code{make-eq-hashtable} and
2128 @code{make-eqv-hashtable}.
2129 @end deffn
2130
2131 @deffn {Scheme Procedure} hashtable-hash-function hashtable
2132 Returns the hash function used by @var{hashtable}. For hash tables
2133 created by @code{make-eq-hashtable} or @code{make-eqv-hashtable},
2134 @code{#f} is returned.
2135 @end deffn
2136
2137 @deffn {Scheme Procedure} hashtable-mutable? hashtable
2138 Returns @code{#t} if @var{hashtable} is mutable, @code{#f} otherwise.
2139 @end deffn
2140
2141 A number of hash functions are provided for convenience:
2142
2143 @deffn {Scheme Procedure} equal-hash obj
2144 Returns an integer hash value for @var{obj}, based on its structure and
2145 current contents. This hash function is suitable for use with
2146 @code{equal?} as an equivalence function.
2147 @end deffn
2148
2149 @deffn {Scheme Procedure} string-hash string
2150 @deffnx {Scheme Procedure} symbol-hash symbol
2151 These procedures are identical to the ones provided by Guile's core
2152 library. @xref{Hash Table Reference}, for documentation.
2153 @end deffn
2154
2155 @deffn {Scheme Procedure} string-ci-hash string
2156 Returns an integer hash value for @var{string} based on its contents,
2157 ignoring case. This hash function is suitable for use with
2158 @code{string-ci=?} as an equivalence function.
2159 @end deffn
2160
2161 @node rnrs enums
2162 @subsubsection rnrs enums
2163
2164 The @code{(rnrs enums (6))} library provides structures and procedures
2165 for working with enumerable sets of symbols. Guile's implementation
2166 defines an @dfn{enum-set} record type that encapsulates a finite set of
2167 distinct symbols, the @dfn{universe}, and a subset of these symbols,
2168 which define the enumeration set.
2169
2170 The SRFI-1 list library provides a number of procedures for performing
2171 set operations on lists; Guile's @code{(rnrs enums)} implementation
2172 makes use of several of them. @xref{SRFI-1 Set Operations}, for
2173 more information.
2174
2175 @deffn {Scheme Procedure} make-enumeration symbol-list
2176 Returns a new enum-set whose universe and enumeration set are both equal
2177 to @var{symbol-list}, a list of symbols.
2178 @end deffn
2179
2180 @deffn {Scheme Procedure} enum-set-universe enum-set
2181 Returns an enum-set representing the universe of @var{enum-set},
2182 an enum-set.
2183 @end deffn
2184
2185 @deffn {Scheme Procedure} enum-set-indexer enum-set
2186 Returns a procedure that takes a single argument and returns the
2187 zero-indexed position of that argument in the universe of
2188 @var{enum-set}, or @code{#f} if its argument is not a member of that
2189 universe.
2190 @end deffn
2191
2192 @deffn {Scheme Procedure} enum-set-constructor enum-set
2193 Returns a procedure that takes a single argument, a list of symbols
2194 from the universe of @var{enum-set}, an enum-set, and returns a new
2195 enum-set with the same universe that represents a subset containing the
2196 specified symbols.
2197 @end deffn
2198
2199 @deffn {Scheme Procedure} enum-set->list enum-set
2200 Returns a list containing the symbols of the set represented by
2201 @var{enum-set}, an enum-set, in the order that they appear in the
2202 universe of @var{enum-set}.
2203 @end deffn
2204
2205 @deffn {Scheme Procedure} enum-set-member? symbol enum-set
2206 @deffnx {Scheme Procedure} enum-set-subset? enum-set1 enum-set2
2207 @deffnx {Scheme Procedure} enum-set=? enum-set1 enum-set2
2208 These procedures test for membership of symbols and enum-sets in other
2209 enum-sets. @code{enum-set-member?} returns @code{#t} if and only if
2210 @var{symbol} is a member of the subset specified by @var{enum-set}.
2211 @code{enum-set-subset?} returns @code{#t} if and only if the universe of
2212 @var{enum-set1} is a subset of the universe of @var{enum-set2} and
2213 every symbol in @var{enum-set1} is present in @var{enum-set2}.
2214 @code{enum-set=?} returns @code{#t} if and only if @var{enum-set1} is a
2215 subset, as per @code{enum-set-subset?} of @var{enum-set2} and vice
2216 versa.
2217 @end deffn
2218
2219 @deffn {Scheme Procedure} enum-set-union enum-set1 enum-set2
2220 @deffnx {Scheme Procedure} enum-set-intersection enum-set1 enum-set2
2221 @deffnx {Scheme Procedure} enum-set-difference enum-set1 enum-set2
2222 These procedures return, respectively, the union, intersection, and
2223 difference of their enum-set arguments.
2224 @end deffn
2225
2226 @deffn {Scheme Procedure} enum-set-complement enum-set
2227 Returns @var{enum-set}'s complement (an enum-set), with regard to its
2228 universe.
2229 @end deffn
2230
2231 @deffn {Scheme Procedure} enum-set-projection enum-set1 enum-set2
2232 Returns the projection of the enum-set @var{enum-set1} onto the universe
2233 of the enum-set @var{enum-set2}.
2234 @end deffn
2235
2236 @deffn {Scheme Syntax} define-enumeration type-name (symbol ...) constructor-syntax
2237 Evaluates to two new definitions: A constructor bound to
2238 @var{constructor-syntax} that behaves similarly to constructors created
2239 by @code{enum-set-constructor}, above, and creates new @var{enum-set}s
2240 in the universe specified by @code{(symbol ...)}; and a ``predicate
2241 macro'' bound to @var{type-name}, which has the following form:
2242
2243 @lisp
2244 (@var{type-name} sym)
2245 @end lisp
2246
2247 If @var{sym} is a member of the universe specified by the @var{symbol}s
2248 above, this form evaluates to @var{sym}. Otherwise, a @code{&syntax}
2249 condition is raised.
2250 @end deffn
2251
2252 @node rnrs
2253 @subsubsection rnrs
2254
2255 The @code{(rnrs (6))} library is a composite of all of the other R6RS
2256 standard libraries---it imports and re-exports all of their exported
2257 procedures and syntactic forms---with the exception of the following
2258 libraries:
2259
2260 @itemize @bullet
2261 @item @code{(rnrs eval (6))}
2262 @item @code{(rnrs mutable-pairs (6))}
2263 @item @code{(rnrs mutable-strings (6))}
2264 @item @code{(rnrs r5rs (6))}
2265 @end itemize
2266
2267 @node rnrs eval
2268 @subsubsection rnrs eval
2269
2270 The @code{(rnrs eval (6)} library provides procedures for performing
2271 ``on-the-fly'' evaluation of expressions.
2272
2273 @deffn {Scheme Procedure} eval expression environment
2274 Evaluates @var{expression}, which must be a datum representation of a
2275 valid Scheme expression, in the environment specified by
2276 @var{environment}. This procedure is identical to the one provided by
2277 Guile's code library; @xref{Fly Evaluation}, for documentation.
2278 @end deffn
2279
2280 @deffn {Scheme Procedure} environment import-spec ...
2281 Constructs and returns a new environment based on the specified
2282 @var{import-spec}s, which must be datum representations of the import
2283 specifications used with the @code{import} form. @xref{R6RS Libraries},
2284 for documentation.
2285 @end deffn
2286
2287 @node rnrs mutable-pairs
2288 @subsubsection rnrs mutable-pairs
2289
2290 The @code{(rnrs mutable-pairs (6))} library provides the @code{set-car!}
2291 and @code{set-cdr!} procedures, which allow the @code{car} and
2292 @code{cdr} fields of a pair to be modified.
2293
2294 These procedures are identical to the ones provide by Guile's core
2295 library. @xref{Pairs}, for documentation. All pairs in Guile are
2296 mutable; consequently, these procedures will never throw the
2297 @code{&assertion} condition described in the R6RS libraries
2298 specification.
2299
2300 @node rnrs mutable-strings
2301 @subsubsection rnrs mutable-strings
2302
2303 The @code{(rnrs mutable-strings (6))} library provides the
2304 @code{string-set!} and @code{string-fill!} procedures, which allow the
2305 content of strings to be modified ``in-place.''
2306
2307 These procedures are identical to the ones provided by Guile's core
2308 library. @xref{String Modification}, for documentation. All strings in
2309 Guile are mutable; consequently, these procedures will never throw the
2310 @code{&assertion} condition described in the R6RS libraries
2311 specification.
2312
2313 @node rnrs r5rs
2314 @subsubsection rnrs r5rs
2315
2316 The @code{(rnrs r5rs (6))} library exports bindings for some procedures
2317 present in R5RS but omitted from the R6RS base library specification.
2318
2319 @deffn {Scheme Procedure} exact->inexact z
2320 @deffnx {Scheme Procedure} inexact->exact z
2321 These procedures are identical to the ones provided by Guile's core
2322 library. @xref{Exactness}, for documentation.
2323 @end deffn
2324
2325 @deffn {Scheme Procedure} quotient n1 n2
2326 @deffnx {Scheme Procedure} remainder n1 n2
2327 @deffnx {Scheme Procedure} modulo n1 n2
2328 These procedures are identical to the ones provided by Guile's core
2329 library. @xref{Integer Operations}, for documentation.
2330 @end deffn
2331
2332 @deffn {Scheme Syntax} delay expr
2333 @deffnx {Scheme Procedure} force promise
2334 The @code{delay} form and the @code{force} procedure are identical to
2335 their counterparts in Guile's core library. @xref{Delayed Evaluation},
2336 for documentation.
2337 @end deffn
2338
2339 @deffn {Scheme Procedure} null-environment n
2340 @deffnx {Scheme Procedure} scheme-report-environment n
2341 These procedures are identical to the ones provided by the
2342 @code{(ice-9 r5rs)} Guile module. @xref{Environments}, for
2343 documentation.
2344 @end deffn
2345
2346 @c r6rs.texi ends here
2347
2348 @c Local Variables:
2349 @c TeX-master: "guile.texi"
2350 @c End: