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