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