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