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