~ chicken-core (master) /manual/Module (scheme base)

   1[[tags: manual]]
   2[[toc:]]
   3
   4== Module scheme
   5
   6This module provides all of CHICKEN's R7RS procedures and macros.
   7These descriptions are based directly on the ''Revised^7 Report on the
   8Algorithmic Language Scheme''.
   9
  10== Expressions
  11
  12Expression types are categorized as primitive or derived. Primitive
  13expression types include variables and procedure calls. Derived
  14expression types are not semantically primitive, but can instead be
  15defined as macros. The distinction which R7RS makes between primitive
  16and derived is unimportant and does not necessarily reflect how it is
  17implemented in CHICKEN itself.
  18
  19=== Primitive expression types
  20
  21==== Variable references
  22
  23<macro><variable></macro><br>
  24
  25An expression consisting of a variable is a variable reference. The
  26value of the variable reference is the value stored in the location to
  27which the variable is bound. It is an error to reference an unbound
  28variable.
  29
  30 (define x 28)
  31 x           ===>  28
  32
  33==== Literal expressions
  34
  35<macro>(quote <datum>)</macro><br>
  36<macro>'<datum></macro><br>
  37<macro><constant></macro><br>
  38
  39(quote <datum>) evaluates to <datum>. <Datum> may be any external
  40representation of a Scheme object. This notation is used to include
  41literal constants in Scheme code.
  42
  43 (quote a)                    ===>  a
  44 (quote #(a b c))             ===>  #(a b c)
  45 (quote (+ 1 2))              ===>  (+ 1 2)
  46
  47(quote <datum>) may be abbreviated as '<datum>. The two notations are
  48equivalent in all respects.
  49
  50 'a                           ===>  a
  51 '#(a b c)                    ===>  #(a b c)
  52 '()                          ===>  ()
  53 '(+ 1 2)                     ===>  (+ 1 2)
  54 '(quote a)                   ===>  (quote a)
  55 ''a                          ===>  (quote a)
  56
  57Numerical constants, string constants, character constants, and boolean
  58constants evaluate "to themselves"; they need not be quoted.
  59
  60 '"abc"             ===>  "abc"
  61 "abc"              ===>  "abc"
  62 '145932            ===>  145932
  63 145932             ===>  145932
  64 '#t                ===>  #t
  65 #t                 ===>  #t
  66 '#(a 10)           ===>  #(a 10)
  67 #(a 10)            ===>  #(a 10)
  68 '#u8(64 65)        ===>  #u8(64 65)
  69 #u8(64 65)         ===>  #u8(64 65)
  70
  71It is an error to alter a constant (i.e. the value of a literal
  72expression) using a mutation procedure like set-car! or string-set!.
  73In the current implementation of CHICKEN, identical constants don't
  74share memory and it is possible to mutate them, but this may change in
  75the future.
  76
  77==== Procedure calls
  78
  79<macro>(<operator> <operand[1]> ...)</macro><br>
  80
  81A procedure call is written by simply enclosing in parentheses
  82expressions for the procedure to be called and the arguments to be
  83passed to it. The operator and operand expressions are evaluated (in an
  84unspecified order) and the resulting procedure is passed the resulting
  85arguments.
  86
  87 (+ 3 4)                           ===>  7
  88 ((if #f + *) 3 4)                 ===>  12
  89
  90A number of procedures are available as the values of variables in the
  91initial environment; for example, the addition and multiplication
  92procedures in the above examples are the values of the variables + and
  93*.  New procedures are created by evaluating lambda
  94expressions. Procedure calls may return any number of values (see the
  95{{values}} procedure [[#control-features|below]]).
  96
  97Procedure calls are also called combinations.
  98
  99Note:   In contrast to other dialects of Lisp, the order of
 100evaluation is unspecified, and the operator expression and the
 101operand expressions are always evaluated with the same evaluation
 102rules.
 103
 104Note:   Although the order of evaluation is otherwise unspecified,
 105the effect of any concurrent evaluation of the operator and operand
 106expressions is constrained to be consistent with some sequential
 107order of evaluation. The order of evaluation may be chosen
 108differently for each procedure call.
 109
 110Note:   In many dialects of Lisp, the empty combination, (), is a
 111legitimate expression. In Scheme, combinations must have at least
 112one subexpression, so () is not a syntactically valid expression.
 113
 114==== Procedures
 115
 116<macro>(lambda <formals> <body>)</macro><br>
 117
 118Syntax: <Formals> should be a formal arguments list as described below,
 119and <body> should be a sequence of one or more expressions.
 120
 121Semantics: A lambda expression evaluates to a procedure. The
 122environment in effect when the lambda expression was evaluated is
 123remembered as part of the procedure. When the procedure is later called
 124with some actual arguments, the environment in which the lambda
 125expression was evaluated will be extended by binding the variables in
 126the formal argument list to fresh locations, the corresponding actual
 127argument values will be stored in those locations, and the expressions
 128in the body of the lambda expression will be evaluated sequentially in
 129the extended environment. The result(s) of the last expression in the
 130body will be returned as the result(s) of the procedure call.
 131
 132 (lambda (x) (+ x x))              ===>  a procedure
 133 ((lambda (x) (+ x x)) 4)          ===>  8
 134 
 135 (define reverse-subtract
 136   (lambda (x y) (- y x)))
 137 (reverse-subtract 7 10)           ===>  3
 138 
 139 (define add4
 140   (let ((x 4))
 141     (lambda (y) (+ x y))))
 142 (add4 6)                          ===>  10
 143
 144<Formals> should have one of the following forms:
 145
 146*   (<variable[1]> ...): The procedure takes a fixed number of
 147    arguments; when the procedure is called, the arguments will be
 148    stored in the bindings of the corresponding variables.
 149
 150*   <variable>: The procedure takes any number of arguments; when the
 151    procedure is called, the sequence of actual arguments is converted
 152    into a newly allocated list, and the list is stored in the binding
 153    of the <variable>.
 154
 155*   (<variable[1]> ... <variable[n]> . <variable[n+1]>): If a
 156    space-delimited period precedes the last variable, then the
 157    procedure takes n or more arguments, where n is the number of
 158    formal arguments before the period (there must be at least one).
 159    The value stored in the binding of the last variable will be a
 160    newly allocated list of the actual arguments left over after all
 161    the other actual arguments have been matched up against the other
 162    formal arguments.
 163
 164It is an error for a <variable> to appear more than once in <formals>.
 165
 166 ((lambda x x) 3 4 5 6)                  ===>  (3 4 5 6)
 167 ((lambda (x y . z) z)
 168  3 4 5 6)                               ===>  (5 6)
 169
 170Each procedure created as the result of evaluating a lambda expression
 171is (conceptually) tagged with a storage location, in order to make eqv?
 172and eq? work on procedures.
 173
 174As an extension to R7RS, CHICKEN also supports "extended" DSSSL style
 175parameter lists, which allows embedded special keywords.  Such a
 176keyword gives a special meaning to the {{<formal>}} it precedes.
 177DSSSL parameter lists are defined by the following grammar:
 178
 179 <parameter-list> ==> <required-parameter>*
 180                      [#!optional <optional-parameter>*]
 181                      [#!rest <rest-parameter>]
 182                      [#!key <keyword-parameter>*]
 183 <required-parameter> ==> <ident>
 184 <optional-parameter> ==> <ident>
 185                          | (<ident> <initializer>)
 186 <rest-parameter> ==> <ident>
 187 <keyword-parameter> ==> <ident>
 188                         | (<ident> <initializer>)
 189 <initializer> ==> <expr>
 190
 191When a procedure is applied to a list of arguments, the parameters and arguments are processed from left to right as follows:
 192
 193* Required-parameters are bound to successive arguments starting with the first argument. It shall be an error if there are fewer arguments than required-parameters.
 194* Next, the optional-parameters are bound with the remaining arguments. If there are fewer arguments than optional-parameters, then the remaining optional-parameters are bound to the result of the evaluation of their corresponding <initializer>, if one was specified, otherwise {{#f}}. The corresponding <initializer> is evaluated in an environment in which all previous parameters have been bound.
 195* If there is a rest-parameter, then it is bound to a list containing all the remaining arguments left over after the argument bindings with required-parameters and optional-parameters have been made. 
 196* If {{#!key}} was specified in the parameter-list, there should be an even number of remaining arguments. These are interpreted as a series of pairs, where the first member of each pair is a keyword specifying the parameter name, and the second member is the corresponding value. If the same keyword occurs more than once in the list of arguments, then the corresponding value of the first keyword is the binding value. If there is no argument for a particular keyword-parameter, then the variable is bound to the result of evaluating <initializer>, if one was specified, otherwise {{#f}}. The corresponding <initializer> is evaluated in an environment in which all previous parameters have been bound. 
 197
 198Needing a special mention is the close relationship between the
 199rest-parameter and possible keyword-parameters.  Declaring a
 200rest-parameter binds up all remaining arguments in a list, as
 201described above. These same remaining arguments are also used for
 202attempted matches with declared keyword-parameters, as described
 203above, in which case a matching keyword-parameter binds to the
 204corresponding value argument at the same time that both the keyword
 205and value arguments are added to the rest parameter list.  Note that
 206for efficiency reasons, the keyword-parameter matching does nothing
 207more than simply attempt to match with pairs that may exist in the
 208remaining arguments.  Extra arguments that don't match are simply
 209unused and forgotten if no rest-parameter has been declared.  Because
 210of this, the caller of a procedure containing one or more
 211keyword-parameters cannot rely on any kind of system error to report
 212wrong keywords being passed in.
 213
 214It shall be an error for an {{<ident>}} to appear more than once in a
 215parameter-list.
 216
 217If there is no rest-parameter and no keyword-parameters in the parameter-list, then it shall be an error for any extra arguments to be passed to the procedure.
 218
 219
 220Example:
 221
 222 ((lambda x x) 3 4 5 6)       => (3 4 5 6)
 223 ((lambda (x y #!rest z) z)
 224  3 4 5 6)                    => (5 6)
 225 ((lambda (x y #!optional z #!rest r #!key i (j 1)) 
 226     (list x y z i: i j: j))
 227  3 4 5 i: 6 i: 7)            => (3 4 5 i: 6 j: 1)
 228
 229
 230
 231==== Conditionals
 232
 233<macro>(if <test> <consequent> <alternate>)</macro><br>
 234<macro>(if <test> <consequent>)</macro><br>
 235
 236Syntax: <Test>, <consequent>, and <alternate> may be arbitrary
 237expressions.
 238
 239Semantics: An if expression is evaluated as follows: first, <test> is
 240evaluated. If it yields a true value (see [[#Booleans|the section
 241about booleans]] below), then <consequent> is evaluated and its
 242value(s) is(are) returned. Otherwise <alternate> is evaluated and its
 243value(s) is(are) returned. If <test> yields a false value and no
 244<alternate> is specified, then the result of the expression is
 245unspecified.
 246
 247 (if (> 3 2) 'yes 'no)                   ===>  yes
 248 (if (> 2 3) 'yes 'no)                   ===>  no
 249 (if (> 3 2)
 250     (- 3 2)
 251     (+ 3 2))                            ===>  1
 252
 253==== Assignments
 254
 255<macro>(set! <variable> <expression>)</macro><br>
 256
 257<Expression> is evaluated, and the resulting value is stored in the
 258location to which <variable> is bound. <Variable> must be bound either
 259in some region enclosing the set! expression or at top level. The
 260result of the set! expression is unspecified.
 261
 262 (define x 2)
 263 (+ x 1)                         ===>  3
 264 (set! x 4)                      ===>  unspecified
 265 (+ x 1)                         ===>  5
 266
 267As an extension to R7RS, {{set!}} for unbound toplevel variables is
 268allowed.  Also, {{(set! (PROCEDURE ...) ...)}} is supported, as CHICKEN
 269implements [[http://srfi.schemers.org/srfi-17/srfi-17.html|SRFI-17]].
 270
 271==== Inclusion
 272
 273<macro>(include STRING1 STRING2 ...)</macro>
 274<macro>(include-ci STRING1 STRING2 ...)</macro>
 275
 276Semantics: Both {{include}} and {{include-ci}} take one or
 277more filenames expressed as string literals, apply an
 278implementation-specific algorithm to find corresponding
 279files, read the contents of the files in the specified order
 280as if by repeated applications of {{read}}, and effectively replace the {{include}}
 281or {{include-ci}} expression with a {{begin}}
 282expression containing what was read from the files. The
 283difference between the two is that {{include-ci}} reads each
 284file as if it began with the {{#!fold-case}} directive, while
 285{{include}} does not.
 286
 287
 288=== Derived expression types
 289
 290The constructs in this section are hygienic.  For reference purposes,
 291these macro definitions will convert most of the constructs described
 292in this section into the primitive constructs described in the
 293previous section.  This does not necessarily mean that's exactly how
 294it's implemented in CHICKEN.
 295
 296==== Conditionals
 297
 298<macro>(cond <clause[1]> <clause[2]> ...)</macro><br>
 299
 300Syntax: Each <clause> should be of the form
 301
 302 (<test> <expression[1]> ...)
 303
 304where <test> is any expression. Alternatively, a <clause> may be of the
 305form
 306
 307 (<test> => <expression>)
 308
 309The last <clause> may be an "else clause," which has the form
 310
 311 (else <expression[1]> <expression[2]> ...).
 312
 313Semantics: A cond expression is evaluated by evaluating the <test>
 314expressions of successive <clause>s in order until one of them
 315evaluates to a true value (see [[#Booleans|the section about
 316booleans]] below). When a <test> evaluates to a true value, then the
 317remaining <expression>s in its <clause> are evaluated in order, and
 318the result(s) of the last <expression> in the <clause> is(are)
 319returned as the result(s) of the entire cond expression. If the
 320selected <clause> contains only the <test> and no <expression>s, then
 321the value of the <test> is returned as the result.  If the selected
 322<clause> uses the => alternate form, then the <expression> is
 323evaluated. Its value must be a procedure that accepts one argument;
 324this procedure is then called on the value of the <test> and the
 325value(s) returned by this procedure is(are) returned by the cond
 326expression. If all <test>s evaluate to false values, and there is no
 327else clause, then the result of the conditional expression is
 328unspecified; if there is an else clause, then its <expression>s are
 329evaluated, and the value(s) of the last one is(are) returned.
 330
 331 (cond ((> 3 2) 'greater)
 332       ((< 3 2) 'less))           ===>  greater
 333 (cond ((> 3 3) 'greater)
 334       ((< 3 3) 'less)
 335       (else 'equal))             ===>  equal
 336 (cond ((assv 'b '((a 1) (b 2))) => cadr)
 337       (else #f))                 ===>  2
 338
 339
 340As an extension to R7RS, CHICKEN also supports the
 341[[http://srfi.schemers.org/srfi-61|SRFI-61]] syntax:
 342
 343 (<generator> <guard> => <expression>)
 344
 345In this situation, {{generator}} is ''always'' evaluated.  Its
 346resulting value(s) are used as argument(s) for the {{guard}}
 347procedure.  Finally, if {{guard}} returns a non-{{#f}} value, the
 348{{expression}} is evaluated by calling it with the result of
 349{{guard}}.  Otherwise, evaluation procedes to the next clause.
 350
 351<macro>(case <key> <clause[1]> <clause[2]> ...)</macro><br>
 352
 353Syntax: <Key> may be any expression. Each <clause> should have the form
 354
 355 ((<datum[1]> ...) <expression[1]> <expression[2]> ...),
 356
 357where each <datum> is an external representation of some object.
 358Alternatively, as per R7RS, a <clause> may be of the form
 359
 360 ((<datum[1]> ...) => <expression>).
 361
 362All the <datum>s must be distinct. The last <clause> may be an
 363"else clause," which has one of the following two forms:
 364
 365 (else <expression[1]> <expression[2]> ...)
 366 (else => <expression>).
 367
 368Semantics: A case expression is evaluated as follows. <Key> is
 369evaluated and its result is compared against each <datum>. If the
 370result of evaluating <key> is equivalent (in the sense of {{eqv?}};
 371see [[#equivalence-predicates|below]]) to a <datum>, then the
 372expressions in the corresponding <clause> are evaluated from left to
 373right and the result(s) of the last expression in the <clause> is(are)
 374returned as the result(s) of the case expression. If the selected
 375<clause> uses the => alternate form (an R7RS extension), then the
 376<expression> is evaluated. Its value must be a procedure that accepts
 377one argument; this procedure is then called on the value of the <key>
 378and the value(s) returned by this procedure is(are) returned by the
 379case expression.  If the result of evaluating <key> is different from
 380every <datum>, then if there is an else clause its expressions are
 381evaluated and the result(s) of the last is(are) the result(s) of the
 382case expression; otherwise the result of the case expression is
 383unspecified.
 384
 385 (case (* 2 3)
 386   ((2 3 5 7) 'prime)
 387   ((1 4 6 8 9) 'composite))             ===>  composite
 388 (case (car '(c d))
 389   ((a) 'a)
 390   ((b) 'b))                             ===>  unspecified
 391 (case (car '(c d))
 392   ((a e i o u) 'vowel)
 393   ((w y) 'semivowel)
 394   (else 'consonant))                    ===>  consonant
 395
 396<macro>(and <test[1]> ...)</macro><br>
 397
 398The <test> expressions are evaluated from left to right, and the value
 399of the first expression that evaluates to a false value (see
 400[[#Booleans|the section about booleans]]) is returned. Any remaining
 401expressions are not evaluated. If all the expressions evaluate to true
 402values, the value of the last expression is returned. If there are no
 403expressions then #t is returned.
 404
 405 (and (= 2 2) (> 2 1))                   ===>  #t
 406 (and (= 2 2) (< 2 1))                   ===>  #f
 407 (and 1 2 'c '(f g))                     ===>  (f g)
 408 (and)                                   ===>  #t
 409
 410<macro>(or <test[1]> ...)</macro><br>
 411
 412The <test> expressions are evaluated from left to right, and the value
 413of the first expression that evaluates to a true value (see
 414[[#Booleans|the section about booleans]]) is returned. Any remaining
 415expressions are not evaluated. If all expressions evaluate to false
 416values, the value of the last expression is returned. If there are no
 417expressions then #f is returned.
 418
 419 (or (= 2 2) (> 2 1))                    ===>  #t
 420 (or (= 2 2) (< 2 1))                    ===>  #t
 421 (or #f #f #f)         ===>  #f
 422 (or (memq 'b '(a b c)) 
 423     (/ 3 0))                            ===>  (b c)
 424
 425<macro>(unless TEST EXP1 EXP2 ...)</macro>
 426
 427Equivalent to:
 428
 429<enscript highlight=scheme>
 430(if (not TEST) (begin EXP1 EXP2 ...))
 431</enscript>
 432
 433<macro>(when TEST EXP1 EXP2 ...)</macro>
 434
 435Equivalent to:
 436
 437<enscript highlight=scheme>
 438(if TEST (begin EXP1 EXP2 ...))
 439</enscript>
 440
 441<macro>(cond-expand <ce-clause1> <ce-clause2> ...)</macro>
 442
 443The {{cond-expand}} expression type provides a way
 444to statically expand different expressions depending on the
 445implementation. A <ce-clause> takes the following form:
 446
 447{{
 448(<feature requirement> <expression> ...)
 449}}
 450
 451The last clause can be an "else clause," which has the form
 452
 453{{
 454(else <expression> ...)
 455}}]
 456
 457A ⟨feature requirement⟩ takes one of the following forms:
 458
 459<feature identifier>
 460
 461{{(library <library name>)}}
 462
 463{{(and <feature requirement> ...)}}
 464
 465{{(or <feature requirement> ...)}}
 466
 467{{(not <feature requirement>)}}
 468
 469Each implementation maintains a list of
 470feature identifiers which are present, as well as a list
 471of libraries which can be imported.
 472The value of a <feature requirement> is determined by replacing each
 473<feature identifier> and {{(library <library name>)}} on the
 474implementation’s lists with {{#t}}, and all other feature identifiers and library names with {{#f}}, then evaluating the resulting expression as a Scheme boolean expression under
 475the normal interpretation of {{and}}, {{or}}, and {{not}}.
 476
 477A {{cond-expand}} is then expanded by evaluating the
 478<feature requirement>s of successive <ce-clause>s in order
 479until one of them returns {{#t}}. When a true clause is found,
 480the corresponding <expression>s are expanded to a {{begin}},
 481and the remaining clauses are ignored.
 482
 483If none of the
 484<feature requirement>s evaluate to {{#t}}, then if there is an
 485{{else}} clause, its <expression>s are included. Otherwise, the
 486behavior of the {{cond}}-expand is unspecified. Unlike {{cond}},
 487{{cond-expand}} does not depend on the value of any variables.
 488
 489The following features are built-in and always available by default:
 490{{chicken}}, {{srfi-0}}, {{srfi-2}}, {{srfi-6}}, {{srfi-8}}, {{srfi-9}},
 491{{srfi-11}}, {{srfi-12}}, {{srfi-15}}, {{srfi-16}}, {{srfi-17}}, {{srfi-23}},
 492{{srfi-26}}, {{srfi-28}}, {{srfi-30}}, {{srfi-31}}, {{srfi-39}}, {{srfi-46}},
 493{{srfi-55}}, {{srfi-61}}, {{srfi-62}}, {{srfi-87}}, {{srfi-88}}.
 494
 495There are also situation-specific feature identifiers: {{compiling}} during
 496compilation, {{csi}} when running in the interpreter, and {{compiler-extension}}
 497when running within the compiler.
 498
 499The symbols returned by the following procedures from
 500[[Module (chicken platform)|(chicken platform)]] are also available
 501as feature-identifiers in all situations: {{(machine-byte-order)}},
 502{{(machine-type)}}, {{(software-type)}}, {{(software-version)}}. For
 503example, the {{machine-type}} class of feature-identifiers include
 504{{arm}}, {{alpha}}, {{mips}}, etc.
 505
 506Platform endianness is indicated by the {{little-endian}} and {{big-endian}}
 507features.
 508
 509In addition the following feature-identifiers may exist: {{cross-chicken}},
 510{{dload}}, {{gchooks}}, {{ptables}}, {{case-insensitive}}.
 511
 512
 513==== Binding constructs
 514
 515The three binding constructs let, let*, and letrec give Scheme a block
 516structure, like Algol 60. The syntax of the three constructs is
 517identical, but they differ in the regions they establish for their
 518variable bindings. In a let expression, the initial values are computed
 519before any of the variables become bound; in a let* expression, the
 520bindings and evaluations are performed sequentially; while in a letrec
 521expression, all the bindings are in effect while their initial values
 522are being computed, thus allowing mutually recursive definitions.
 523
 524<macro>(let <bindings> <body>)</macro><br>
 525
 526Syntax: <Bindings> should have the form
 527
 528 ((<variable[1]> <init[1]>) ...),
 529
 530where each <init> is an expression, and <body> should be a sequence of
 531one or more expressions. It is an error for a <variable> to appear more
 532than once in the list of variables being bound.
 533
 534Semantics: The <init>s are evaluated in the current environment (in
 535some unspecified order), the <variable>s are bound to fresh locations
 536holding the results, the <body> is evaluated in the extended
 537environment, and the value(s) of the last expression of <body> is(are)
 538returned. Each binding of a <variable> has <body> as its region.
 539
 540 (let ((x 2) (y 3))
 541   (* x y))                              ===>  6
 542 
 543 (let ((x 2) (y 3))
 544   (let ((x 7)
 545         (z (+ x y)))
 546     (* z x)))                           ===>  35
 547
 548See also "named let", [[#iteration|below]].
 549
 550<macro>(let* <bindings> <body>)</macro><br>
 551
 552Syntax: <Bindings> should have the form
 553
 554 ((<variable[1]> <init[1]>) ...),
 555
 556and <body> should be a sequence of one or more expressions.
 557
 558Semantics: Let* is similar to let, but the bindings are performed
 559sequentially from left to right, and the region of a binding indicated
 560by (<variable> <init>) is that part of the let* expression to the right
 561of the binding. Thus the second binding is done in an environment in
 562which the first binding is visible, and so on.
 563
 564 (let ((x 2) (y 3))
 565   (let* ((x 7)
 566          (z (+ x y)))
 567     (* z x)))                     ===>  70
 568
 569<macro>(letrec <bindings> <body>)</macro><br>
 570
 571Syntax: <Bindings> should have the form
 572
 573 ((<variable[1]> <init[1]>) ...),
 574
 575and <body> should be a sequence of one or more expressions. It is an
 576error for a <variable> to appear more than once in the list of
 577variables being bound.
 578
 579Semantics: The <variable>s are bound to fresh locations holding
 580undefined values, the <init>s are evaluated in the resulting
 581environment (in some unspecified order), each <variable> is assigned to
 582the result of the corresponding <init>, the <body> is evaluated in the
 583resulting environment, and the value(s) of the last expression in
 584<body> is(are) returned. Each binding of a <variable> has the entire
 585letrec expression as its region, making it possible to define mutually
 586recursive procedures.
 587
 588 (letrec ((even?
 589           (lambda (n)
 590             (if (zero? n)
 591                 #t
 592                 (odd? (- n 1)))))
 593          (odd?
 594           (lambda (n)
 595             (if (zero? n)
 596                 #f
 597                 (even? (- n 1))))))
 598   (even? 88))
 599                         ===>  #t
 600
 601One restriction on letrec is very important: it must be possible to
 602evaluate each <init> without assigning or referring to the value of any
 603<variable>. If this restriction is violated, then it is an error. The
 604restriction is necessary because Scheme passes arguments by value
 605rather than by name. In the most common uses of letrec, all the <init>s
 606are lambda expressions and the restriction is satisfied automatically.
 607
 608<macro>(letrec* <bindings> <body>) </macro>
 609
 610Syntax: <Bindings> has the form {{((<variable[1]> <init[1]>) ...)}}, and 
 611<body> is a sequence of zero or more
 612definitions followed by one or more expressions as described in section 4.1.4.
 613It is an error for a <variable> to appear more than once in the list of
 614variables being bound.
 615
 616Semantics: The <variable>s are bound to fresh locations, each <variable> is
 617assigned in left-to-right order to the result of evaluating the corresponding
 618<init> (interleaving evaluations and assignments), the <body> is evaluated in
 619the resulting environment, and the values of the last expression in <body> are
 620returned. Despite the left-to-right evaluation and assignment order, each
 621binding of a <variable> has the entire letrec* expression as its region, making
 622it possible to define mutually recursive procedures.
 623
 624If it is not possible to evaluate each <init> without assigning or referring to
 625the value of the corresponding <variable> or the <variable> of any of the
 626bindings that follow it in <bindings>, it is an error. Another restriction is
 627that it is an error to invoke the continuation of an <init> more than once.
 628
 629  ;; Returns the arithmetic, geometric, and
 630  ;; harmonic means of a nested list of numbers
 631  (define (means ton)
 632    (letrec*
 633       ((mean
 634          (lambda (f g)
 635            (f (/ (sum g ton) n))))
 636        (sum
 637          (lambda (g ton)
 638            (if (null? ton)
 639              (+)
 640              (if (number? ton)
 641                  (g ton)
 642                  (+ (sum g (car ton))
 643                     (sum g (cdr ton)))))))
 644        (n (sum (lambda (x) 1) ton)))
 645      (values (mean values values)
 646              (mean exp log)
 647              (mean / /))))
 648
 649Evaluating {{(means '(3 (1 4)))}} returns three values: 8/3, 2.28942848510666
 650(approximately), and 36/19.
 651
 652<macro>(let-values <mv binding spec> <body>)</macro>
 653
 654Syntax: <Mv binding spec> has the form {{((<formals[1]> <init[1]>) ...)}}, 
 655where each <init> is an expression, and <body> is
 656zero or more definitions followed by a sequence of one or more expressions as
 657described in section 4.1.4. It is an error for a variable to appear more than
 658once in the set of <formals>.
 659
 660Semantics: The <init>s are evaluated in the current environment (in some
 661unspecified order) as if by invoking call-with-values, and the variables
 662occurring in the <formals> are bound to fresh locations holding the values
 663returned by the <init>s, where the <formals> are matched to the return values
 664in the same way that the <formals> in a lambda expression are matched to the
 665arguments in a procedure call. Then, the <body> is evaluated in the extended
 666environment, and the values of the last expression of <body> are returned. Each
 667binding of a <variable> has <body> as its region.
 668
 669It is an error if the <formals> do not match the number of values returned by
 670the corresponding <init>.
 671
 672  (let-values (((root rem) (exact-integer-sqrt 32)))
 673    (* root rem))                 ==>  35
 674
 675<macro>(let*-values <mv binding spec> <body>)</macro>
 676
 677Syntax: <Mv binding spec> has the form {{((<formals> <init>) ...)}},
 678and <body> is a sequence of zero or more definitions
 679followed by one or more expressions as described in section 4.1.4. In each
 680<formals>, it is an error if any variable appears more than once.
 681
 682Semantics: The let*-values construct is similar to let-values, but the <init>s
 683are evaluated and bindings created sequentially from left to right, with the
 684region of the bindings of each <formals> including the <init>s to its right as
 685well as <body>. Thus the second <init> is evaluated in an environment in which
 686the first set of bindings is visible and initialized, and so on.
 687
 688  (let ((a 'a) (b 'b) (x 'x) (y 'y))
 689    (let*-values (((a b) (values x y))
 690                  ((x y) (values a b)))
 691      (list a b x y)))      ⟹ (x y x y)
 692
 693==== Sequencing
 694
 695<macro>(begin <expression[1]> <expression[2]> ...)</macro><br>
 696
 697The <expression>s are evaluated sequentially from left to right, and
 698the value(s) of the last <expression> is(are) returned. This expression
 699type is used to sequence side effects such as input and output.
 700
 701 (define x 0)
 702 
 703 (begin (set! x 5)
 704        (+ x 1))                          ===>  6
 705 
 706 (begin (display "4 plus 1 equals ")
 707        (display (+ 4 1)))                ===>  unspecified
 708   and prints  4 plus 1 equals 5
 709
 710As an extension to R7RS, CHICKEN also allows {{(begin)}} without body
 711expressions in any context, not just at toplevel.  This simply
 712evaluates to the unspecified value.
 713
 714
 715==== Iteration
 716
 717<macro>(do ((<variable[1]> <init[1]> <step[1]>) ...) (<test> <expression> ...) <command> ...)</macro><br>
 718
 719Do is an iteration construct. It specifies a set of variables to be
 720bound, how they are to be initialized at the start, and how they are to
 721be updated on each iteration. When a termination condition is met, the
 722loop exits after evaluating the <expression>s.
 723
 724Do expressions are evaluated as follows: The <init> expressions are
 725evaluated (in some unspecified order), the <variable>s are bound to
 726fresh locations, the results of the <init> expressions are stored in
 727the bindings of the <variable>s, and then the iteration phase begins.
 728
 729Each iteration begins by evaluating <test>; if the result is false
 730(see [[#Booleans|the section about booleans]]), then the <command>
 731expressions are evaluated in order for effect, the <step> expressions
 732are evaluated in some unspecified order, the <variable>s are bound to
 733fresh locations, the results of the <step>s are stored in the bindings
 734of the <variable>s, and the next iteration begins.
 735
 736If <test> evaluates to a true value, then the <expression>s are
 737evaluated from left to right and the value(s) of the last <expression>
 738is(are) returned. If no <expression>s are present, then the value of
 739the do expression is unspecified.
 740
 741The region of the binding of a <variable> consists of the entire do
 742expression except for the <init>s. It is an error for a <variable> to
 743appear more than once in the list of do variables.
 744
 745A <step> may be omitted, in which case the effect is the same as if
 746(<variable> <init> <variable>) had been written instead of (<variable>
 747<init>).
 748
 749 (do ((vec (make-vector 5))
 750      (i 0 (+ i 1)))
 751     ((= i 5) vec)
 752   (vector-set! vec i i))                    ===>  #(0 1 2 3 4)
 753 
 754 (let ((x '(1 3 5 7 9)))
 755   (do ((x x (cdr x))
 756        (sum 0 (+ sum (car x))))
 757       ((null? x) sum)))                     ===>  25
 758
 759<macro>(let <variable> <bindings> <body>)</macro><br>
 760
 761"Named let" is a variant on the syntax of let which provides a more
 762general looping construct than do and may also be used to express
 763recursions. It has the same syntax and semantics as ordinary let except
 764that <variable> is bound within <body> to a procedure whose formal
 765arguments are the bound variables and whose body is <body>. Thus the
 766execution of <body> may be repeated by invoking the procedure named by
 767<variable>.
 768
 769 (let loop ((numbers '(3 -2 1 6 -5))
 770            (nonneg '())
 771            (neg '()))
 772   (cond ((null? numbers) (list nonneg neg))
 773         ((>= (car numbers) 0)
 774          (loop (cdr numbers)
 775                (cons (car numbers) nonneg)
 776                neg))
 777         ((< (car numbers) 0)
 778          (loop (cdr numbers)
 779                nonneg
 780                (cons (car numbers) neg)))))
 781                 ===>  ((6 1 3) (-5 -2))
 782
 783====  Dynamic bindings
 784
 785The dynamic extent of a procedure call is the time between when it is initiated
 786and when it returns. In Scheme, {{call-with-current-continuation}}
 787allows reentering a dynamic extent after its procedure call has returned. Thus,
 788the dynamic extent of a call might not be a single, continuous time period.
 789
 790This sections introduces parameter objects, which can be bound to new values
 791for the duration of a dynamic extent. The set of all parameter bindings at a
 792given time is called the dynamic environment.
 793
 794<procedure>(make-parameter init [converter])</procedure>
 795
 796Returns a newly allocated parameter object, which is a procedure that accepts
 797zero arguments and returns the value associated with the parameter object.
 798Initially, this value is the value of {{(converter init)}}, or of {{init}} 
 799if the conversion procedure {{converter}} is not specified. The associated value can be temporarily changed
 800using {{parameterize}}, which is described below.
 801
 802The effect of passing arguments to a parameter object is
 803implementation-dependent.
 804
 805<syntax>(parameterize ((<param[1]> <value[1]>) ...) <body>)</syntax>
 806
 807Syntax: Both <param[1]> and <value[1]> are expressions.
 808
 809It is an error if the value of any <param> expression is not a parameter
 810object.
 811
 812Semantics: A parameterize expression is used to change the values returned by
 813specified parameter objects during the evaluation of the body.
 814
 815The <param> and <value> expressions are evaluated in an unspecified order. The
 816<body> is evaluated in a dynamic environment in which calls to the parameters
 817return the results of passing the corresponding values to the conversion
 818procedure specified when the parameters were created. Then the previous values
 819of the parameters are restored without passing them to the conversion
 820procedure. The results of the last expression in the <body> are returned as the
 821results of the entire parameterize expression.
 822
 823Note: If the conversion procedure is not idempotent, the results of 
 824(parameterize ((x (x))) ...), which appears to bind the parameter
 825
 826x to its current value, might not be what the user expects.
 827
 828If an implementation supports multiple threads of execution, then parameterize
 829must not change the associated values of any parameters in any thread other
 830than the current thread and threads created inside <body>.
 831
 832Parameter objects can be used to specify configurable settings for a
 833computation without the need to pass the value to every procedure in the call
 834chain explicitly.
 835
 836  (define radix
 837    (make-parameter
 838     10
 839     (lambda (x)
 840       (if (and (exact-integer? x) (<= 2 x 16))
 841           x
 842           (error "invalid radix")))))
 843
 844  (define (f n) (number->string n (radix)))
 845
 846  (f 12)                                        ==> "12"
 847  (parameterize ((radix 2))
 848    (f 12))                                     ==> "1100"
 849  (f 12)                                        ==> "12"
 850
 851  (radix 16)                                    ==> unspecified
 852
 853  (parameterize ((radix 0))
 854    (f 12))                                     ==> error
 855
 856==== Exception handling
 857
 858<macro>(guard (<variable> <cond clause[1]> <cond clause[2]> ...) <body>)</macro>
 859
 860Syntax: Each <cond clause> is as in the specification of cond.
 861
 862Semantics: The <body> is evaluated with an exception handler that binds the
 863raised object (see {{raise}}) to <variable> and, within the scope
 864of that binding, evaluates the clauses as if they were the clauses of a cond
 865expression. That implicit cond expression is evaluated with the continuation
 866and dynamic environment of the guard expression. If every <cond clause>'s
 867<test> evaluates to #f and there is no else clause, then raise-continuable is
 868invoked on the raised object within the dynamic environment of the original
 869call to raise or raise-continuable, except that the current exception handler
 870is that of the guard expression.
 871
 872    (guard (condition
 873             ((assq 'a condition) => cdr)
 874             ((assq 'b condition)))
 875      (raise (list (cons 'a 42))))
 876    ==> 42
 877
 878    (guard (condition
 879             ((assq 'a condition) => cdr)
 880             ((assq 'b condition)))
 881      (raise (list (cons 'b 23))))
 882    ==> (b . 23)
 883
 884==== Quasiquotation
 885
 886<macro>(quasiquote <qq template>)</macro><br>
 887<macro>`<qq template></macro><br>
 888
 889"Backquote" or "quasiquote" expressions are useful for constructing
 890a list or vector structure when most but not all of the desired
 891structure is known in advance. If no commas appear within the <qq
 892template>, the result of evaluating `<qq template> is equivalent to the
 893result of evaluating '<qq template>. If a comma appears within the <qq
 894template>, however, the expression following the comma is evaluated
 895("unquoted") and its result is inserted into the structure instead of
 896the comma and the expression. If a comma appears followed immediately
 897by an at-sign (@), then the following expression must evaluate to a
 898list; the opening and closing parentheses of the list are then
 899"stripped away" and the elements of the list are inserted in place of
 900the comma at-sign expression sequence. A comma at-sign should only
 901appear within a list or vector <qq template>.
 902
 903 `(list ,(+ 1 2) 4)          ===>  (list 3 4)
 904 (let ((name 'a)) `(list ,name ',name))           
 905                 ===>  (list a (quote a))
 906 `(a ,(+ 1 2) ,@(map abs '(4 -5 6)) b)           
 907                 ===>  (a 3 4 5 6 b)
 908 `(( foo ,(- 10 3)) ,@(cdr '(c)) . ,(car '(cons)))           
 909                 ===>  ((foo 7) . cons)
 910 `#(10 5 ,(sqrt 4) ,@(map sqrt '(16 9)) 8)           
 911                 ===>  #(10 5 2 4 3 8)
 912
 913Quasiquote forms may be nested. Substitutions are made only for
 914unquoted components appearing at the same nesting level as the
 915outermost backquote. The nesting level increases by one inside each
 916successive quasiquotation, and decreases by one inside each
 917unquotation.
 918
 919 `(a `(b ,(+ 1 2) ,(foo ,(+ 1 3) d) e) f)           
 920                 ===>  (a `(b ,(+ 1 2) ,(foo 4 d) e) f)
 921 (let ((name1 'x)
 922       (name2 'y))
 923   `(a `(b ,,name1 ,',name2 d) e))           
 924                 ===>  (a `(b ,x ,'y d) e)
 925
 926The two notations `<qq template> and (quasiquote <qq template>) are
 927identical in all respects. ,<expression> is identical to (unquote
 928<expression>), and ,@<expression> is identical to (unquote-splicing
 929<expression>). The external syntax generated by write for two-element
 930lists whose car is one of these symbols may vary between
 931implementations.
 932
 933 (quasiquote (list (unquote (+ 1 2)) 4))           
 934                 ===>  (list 3 4)
 935 '(quasiquote (list (unquote (+ 1 2)) 4))           
 936                 ===>  `(list ,(+ 1 2) 4)
 937      i.e., (quasiquote (list (unquote (+ 1 2)) 4))
 938
 939Unpredictable behavior can result if any of the symbols quasiquote,
 940unquote, or unquote-splicing appear in positions within a <qq template>
 941otherwise than as described above.
 942
 943=== Macros
 944
 945Scheme programs can define and use new derived expression types, called
 946macros. Program-defined expression types have the syntax
 947
 948 (<keyword> <datum> ...)
 949
 950where <keyword> is an identifier that uniquely determines the
 951expression type. This identifier is called the syntactic keyword, or
 952simply keyword, of the macro. The number of the <datum>s, and their
 953syntax, depends on the expression type.
 954
 955Each instance of a macro is called a use of the macro. The set of rules
 956that specifies how a use of a macro is transcribed into a more
 957primitive expression is called the transformer of the macro.
 958
 959The macro definition facility consists of two parts:
 960
 961*   A set of expressions used to establish that certain identifiers are
 962    macro keywords, associate them with macro transformers, and control
 963    the scope within which a macro is defined, and
 964
 965*   a pattern language for specifying macro transformers.
 966
 967The syntactic keyword of a macro may shadow variable bindings, and
 968local variable bindings may shadow keyword bindings. All macros defined
 969using the pattern language are "hygienic" and "referentially
 970transparent" and thus preserve Scheme's lexical scoping:
 971
 972*   If a macro transformer inserts a binding for an identifier
 973    (variable or keyword), the identifier will in effect be renamed
 974    throughout its scope to avoid conflicts with other identifiers.
 975    Note that a define at top level may or may not introduce a binding;
 976    this depends on whether the binding already existed before (in which
 977    case its value will be overridden).
 978
 979*   If a macro transformer inserts a free reference to an identifier,
 980    the reference refers to the binding that was visible where the
 981    transformer was specified, regardless of any local bindings that
 982    may surround the use of the macro.
 983
 984==== Binding constructs for syntactic keywords
 985
 986Let-syntax and letrec-syntax are analogous to let and letrec, but they
 987bind syntactic keywords to macro transformers instead of binding
 988variables to locations that contain values. Syntactic keywords may also
 989be bound at top level.
 990
 991<macro>(let-syntax <bindings> <body>)</macro><br>
 992
 993Syntax: <Bindings> should have the form
 994
 995 ((<keyword> <transformer spec>) ...)
 996
 997Each <keyword> is an identifier, each <transformer spec> is an instance
 998of syntax-rules, and <body> should be a sequence of one or more
 999expressions. It is an error for a <keyword> to appear more than once in
 1000the list of keywords being bound.
1001
1002Semantics: The <body> is expanded in the syntactic environment obtained
1003by extending the syntactic environment of the let-syntax expression
1004with macros whose keywords are the <keyword>s, bound to the specified
1005transformers. Each binding of a <keyword> has <body> as its region.
1006
1007 (let-syntax ((when (syntax-rules ()
1008                      ((when test stmt1 stmt2 ...)
1009                       (if test
1010                           (begin stmt1
1011                                  stmt2 ...))))))
1012   (let ((if #t))
1013     (when if (set! if 'now))
1014     if))                                   ===>  now
1015 
1016 (let ((x 'outer))
1017   (let-syntax ((m (syntax-rules () ((m) x))))
1018     (let ((x 'inner))
1019       (m))))                               ===>  outer
1020
1021<macro>(letrec-syntax <bindings> <body>)</macro><br>
1022
1023Syntax: Same as for let-syntax.
1024
1025Semantics: The <body> is expanded in the syntactic environment obtained
1026by extending the syntactic environment of the letrec-syntax expression
1027with macros whose keywords are the <keyword>s, bound to the specified
1028transformers. Each binding of a <keyword> has the <bindings> as well as
1029the <body> within its region, so the transformers can transcribe
1030expressions into uses of the macros introduced by the letrec-syntax
1031expression.
1032
1033 (letrec-syntax
1034   ((my-or (syntax-rules ()
1035             ((my-or) #f)
1036             ((my-or e) e)
1037             ((my-or e1 e2 ...)
1038              (let ((temp e1))
1039                (if temp
1040                    temp
1041                    (my-or e2 ...)))))))
1042   (let ((x #f)
1043         (y 7)
1044         (temp 8)
1045         (let odd?)
1046         (if even?))
1047     (my-or x
1048            (let temp)
1049            (if y)
1050            y)))                ===>  7
1051
1052==== Pattern language
1053
1054A <transformer spec> has the following form:
1055
1056 (syntax-rules <literals> <syntax rule> ...)
1057
1058Syntax: <Literals> is a list of identifiers and each <syntax rule>
1059should be of the form
1060
1061 (<pattern> <template>)
1062
1063The <pattern> in a <syntax rule> is a list <pattern> that begins with
1064the keyword for the macro.
1065
1066A <pattern> is either an identifier, a constant, or one of the
1067following
1068
1069 (<pattern> ...)
1070 (<pattern> <pattern> ... . <pattern>)
1071 (<pattern> ... <pattern> <ellipsis> <pattern> ...)
1072 #(<pattern> ...)
1073 #(<pattern> ... <pattern> <ellipsis>)
1074
1075and a template is either an identifier, a constant, or one of the
1076following
1077
1078 (<element> ...)
1079 (<element> <element> ... . <template>)
1080 (<ellipsis> <template>)
1081 #(<element> ...)
1082
1083where an <element> is a <template> optionally followed by an <ellipsis>
1084and an <ellipsis> is the identifier "...".
1085
1086Semantics: An instance of syntax-rules produces a new macro transformer
1087by specifying a sequence of hygienic rewrite rules. A use of a macro
1088whose keyword is associated with a transformer specified by
1089syntax-rules is matched against the patterns contained in the <syntax
1090rule>s, beginning with the leftmost <syntax rule>. When a match is
1091found, the macro use is transcribed hygienically according to the
1092template.
1093
1094An identifier appearing within a <pattern> can be an underscore ({{_}}), a literal
1095identifier listed in the list of <pattern literal>s, or the <ellipsis>. All
1096other identifiers appearing within a <pattern> are pattern variables.
1097
1098The keyword at the beginning of the pattern in a <syntax rule> is not involved
1099in the matching and is considered neither a pattern variable nor a literal
1100identifier.
1101
1102Pattern variables match arbitrary input elements and are used to refer to
1103elements of the input in the template. It is an error for the same pattern
1104variable to appear more than once in a <pattern>.
1105
1106Underscores also match arbitrary input elements but are not pattern variables
1107and so cannot be used to refer to those elements. If an underscore appears in
1108the <pattern literal>s list, then that takes precedence and underscores in the
1109<pattern> match as literals. Multiple underscores can appear in a <pattern>.
1110
1111Identifiers that appear in (<pattern literal> …) are interpreted as literal
1112identifiers to be matched against corresponding elements of the input. An
1113element in the input matches a literal identifier if and only if it is an
1114identifier and either both its occurrence in the macro expression and its
1115occurrence in the macro definition have the same lexical binding, or the two
1116identifiers are the same and both have no lexical binding.
1117
1118A subpattern followed by <ellipsis> can match zero or more elements of the
1119input, unless <ellipsis> appears in the <pattern literal>s, in which case it is
1120matched as a literal.
1121
1122More formally, an input form F matches a pattern P if and only if:
1123
1124*   P is an underscore (_).
1125
1126*   P is a non-literal identifier; or
1127
1128*   P is a literal identifier and F is an identifier with the same
1129    binding; or
1130
1131*   P is a list (P[1] ... P[n]) and F is a list of n forms that match P
1132    [1] through P[n], respectively; or
1133
1134*   P is an improper list (P[1] P[2] ... P[n] . P[n+1]) and F is a list
1135    or improper list of n or more forms that match P[1] through P[n],
1136    respectively, and whose nth "cdr" matches P[n+1]; or
1137
1138*   P is of the form (P[1] … P[k] P[e] <ellipsis> P[m+1] ... P[n] . P[x]) where E
1139    is a list or improper list of n elements, the first k of which match P[1]
1140    through P[k], whose next m−k elements each match P[e], whose remaining n−m
1141    elements match P[m+1] through P[n], and whose nth and final cdr matches P[x
1142    ]; or
1143
1144*   P is a vector of the form #(P[1] ... P[n]) and F is a vector of n
1145    forms that match P[1] through P[n]; or
1146
1147*   P is of the form #(P[1] ... P[k] P[e] <ellipsis> P[m+1] ... P[n]) where E is a
1148    vector of n elements the first k of which match P[1] through P[k], whose
1149    next m−k elements each match P[e], and whose remaining n−m elements match P
1150    [m+1] through P[n]; or
1151
1152*   P is a datum and F is equal to P in the sense of the equal?
1153    procedure.
1154
1155It is an error to use a macro keyword, within the scope of its binding,
1156in an expression that does not match any of the patterns.
1157
1158When a macro use is transcribed according to the template of the matching
1159<syntax rule>, pattern variables that occur in the template are replaced by the
1160elements they match in the input. Pattern variables that occur in subpatterns
1161followed by one or more instances of the identifier <ellipsis> are allowed only
1162in subtemplates that are followed by as many instances of <ellipsis>. They are
1163replaced in the output by all of the elements they match in the input,
1164distributed as indicated. It is an error if the output cannot be built up as
1165specified.
1166
1167Identifiers that appear in the template but are not pattern variables or the
1168identifier <ellipsis> are inserted into the output as literal identifiers. If a
1169literal identifier is inserted as a free identifier then it refers to the
1170binding of that identifier within whose scope the instance of syntax-rules
1171appears. If a literal identifier is inserted as a bound identifier then it is
1172in effect renamed to prevent inadvertent captures of free identifiers.
1173
1174A template of the form (<ellipsis> <template>) is identical to <template>,
1175except that ellipses within the template have no special meaning. That is, any
1176ellipses contained within <template> are treated as ordinary identifiers. In
1177particular, the template (<ellipsis> <ellipsis>) produces a single <ellipsis>.
1178This allows syntactic abstractions to expand into code containing ellipses.
1179
1180{{
1181(define-syntax be-like-begin
1182  (syntax-rules ()
1183    ((be-like-begin name)
1184     (define-syntax name
1185       (syntax-rules ()
1186         ((name expr (... ...))
1187          (begin expr (... ...))))))))
1188
1189(be-like-begin sequence)
1190
1191(sequence 1 2 3 4)  ==> 4 
1192}}
1193
1194As an example, if {{let}} and {{cond}} have their standard meaning
1195then they are hygienic (as required) and the following is not an
1196error.
1197
1198 (let ((=> #f))
1199   (cond (#t => 'ok)))                   ===> ok
1200
1201The macro transformer for cond recognizes => as a local variable, and
1202hence an expression, and not as the top-level identifier =>, which the
1203macro transformer treats as a syntactic keyword. Thus the example
1204expands into
1205
1206 (let ((=> #f))
1207   (if #t (begin => 'ok)))
1208
1209instead of
1210
1211 (let ((=> #f))
1212   (let ((temp #t))
1213     (if temp ('ok temp))))
1214
1215which would result in an invalid procedure call.
1216
1217====  Signaling errors in macro transformers
1218
1219<macro>(syntax-error <message> <args> ...)</macro>
1220
1221{{syntax-error}} behaves similarly to {{error}} except that implementations with
1222an expansion pass separate from evaluation should signal an error as soon as 
1223{{syntax-error}} is expanded. This can be used as a syntax-rules <template> for a
1224<pattern> that is an invalid use of the macro, which can provide more
1225descriptive error messages. <message> is a string literal, and <args> arbitrary
1226expressions providing additional information. Applications cannot count on
1227being able to catch syntax errors with exception handlers or guards.
1228
1229 (define-syntax simple-let
1230   (syntax-rules ()
1231     ((_ (head ... ((x . y) val) . tail)
1232         body1 body2 ...)
1233      (syntax-error
1234       "expected an identifier but got"
1235       (x . y)))
1236     ((_ ((name val) ...) body1 body2 ...)
1237      ((lambda (name ...) body1 body2 ...)
1238        val ...))))
1239
1240
1241== Program structure
1242
1243=== Programs
1244
1245A Scheme program consists of a sequence of expressions, definitions,
1246and syntax definitions. Expressions are described in chapter 4;
1247definitions and syntax definitions are the subject of the rest of the
1248present chapter.
1249
1250Programs are typically stored in files or entered interactively to a
1251running Scheme system, although other paradigms are possible;
1252questions of user interface lie outside the scope of this
1253report. (Indeed, Scheme would still be useful as a notation for
1254expressing computational methods even in the absence of a mechanical
1255implementation.)
1256
1257Definitions and syntax definitions occurring at the top level of a
1258program can be interpreted declaratively. They cause bindings to be
1259created in the top level environment or modify the value of existing
1260top-level bindings. Expressions occurring at the top level of a
1261program are interpreted imperatively; they are executed in order when
1262the program is invoked or loaded, and typically perform some kind of
1263initialization.
1264
1265At the top level of a program (begin <form1> ...) is equivalent to the
1266sequence of expressions, definitions, and syntax definitions that form
1267the body of the begin.
1268
1269===  Import declarations
1270
1271<macro>(import IMPORT-SET ...)</macro>
1272
1273An import declaration provides a way to import identifiers exported by a
1274library. Each <import set> names a set of bindings from a library and possibly
1275specifies local names for the imported bindings. It takes one of the following
1276forms:
1277
1278* <library name>
1279
1280* {{(only <import set> <identifier> ...)}}
1281
1282* {{(except <import set> <identifier> ...)}}
1283
1284* {{(prefix <import set> <identifier>)}}
1285
1286* {{(rename <import set> (<identifier[1]> <identifier[2]>) ...)}}
1287
1288In the first form, all of the identifiers in the named library’s export clauses
1289are imported with the same names (or the exported names if exported with rename
1290). The additional <import set> forms modify this set as follows:
1291
1292*   only produces a subset of the given <import set> including only the listed
1293    identifiers (after any renaming). It is an error if any of the listed
1294    identifiers are not found in the original set.
1295
1296*   except produces a subset of the given <import set>, excluding the listed
1297    identifiers (after any renaming). It is an error if any of the listed
1298    identifiers are not found in the original set.
1299
1300*   rename modifies the given <import set>, replacing each instance of
1301    <identifier[1]> with <identifier[2]>. It is an error if any of the listed
1302    <identifier[1]>s are not found in the original set.
1303
1304*   prefix automatically renames all identifiers in the given <import set>,
1305    prefixing each with the specified <identifier>.
1306
1307=== Definitions
1308
1309Definitions are valid in some, but not all, contexts where expressions
1310are allowed. They are valid only at the top level of a <program> and
1311at the beginning of a <body>.
1312
1313A definition should have one of the following forms:
1314
1315<macro>(define <variable> <expression>)</macro><br>
1316<macro>(define (<variable> <formals>) <body>)</macro><br>
1317
1318<Formals> should be either a sequence of zero or more variables, or a
1319sequence of one or more variables followed by a space-delimited period
1320and another variable (as in a lambda expression). This form is
1321equivalent to
1322
1323 (define <variable>
1324   (lambda (<formals>) <body>)).
1325
1326<macro>(define <variable>)</macro>
1327
1328This form is a CHICKEN extension to R7RS, and is equivalent to
1329
1330 (define <variable> (void))
1331
1332<macro>(define (<variable> . <formal>) <body>)</macro><br>
1333
1334<Formal> should be a single variable. This form is equivalent to
1335
1336 (define <variable>
1337   (lambda <formal> <body>)).
1338
1339<macro>(define ((<variable> <formal> ...) ...) <body>)</macro><br>
1340
1341As an extension to R7RS, CHICKEN allows ''curried'' definitions, where
1342the variable name may also be a list specifying a name and a nested
1343lambda list. For example,
1344
1345 (define ((make-adder x) y) (+ x y))
1346
1347is equivalent to
1348
1349 (define (make-adder x) (lambda (y) (+ x y))).
1350
1351This type of curried definition can be nested arbitrarily and combined
1352with dotted tail notation or DSSSL keywords.
1353
1354==== Top level definitions
1355
1356At the top level of a program, a definition
1357
1358 (define <variable> <expression>)
1359
1360has essentially the same effect as the assignment expression
1361
1362 (set! <variable> <expression>)
1363
1364if <variable> is bound. If <variable> is not bound, however, then the
1365definition will bind <variable> to a new location before performing
1366the assignment, whereas it would be an error to perform a set! on an
1367unbound variable in standard Scheme.  In CHICKEN, {{set!}} at toplevel
1368has the same effect as a definition, unless inside a module, in which
1369case it is an error.
1370
1371 (define add3
1372   (lambda (x) (+ x 3)))
1373 (add3 3)                         ===>  6
1374 (define first car)
1375 (first '(1 2))                   ===>  1
1376
1377Some implementations of Scheme use an initial environment in which all
1378possible variables are bound to locations, most of which contain
1379undefined values. Top level definitions in such an implementation are
1380truly equivalent to assignments.  In CHICKEN, attempting to evaluate
1381an unbound identifier will result in an error, but you ''can'' use
1382{{set!}} to bind an initial value to it.
1383
1384==== Internal definitions
1385
1386Definitions may occur at the beginning of a <body> (that is, the body
1387of a lambda, let, let*, letrec, let-syntax, or letrec-syntax
1388expression or that of a definition of an appropriate form). Such
1389definitions are known as internal definitions as opposed to the top
1390level definitions described above. The variable defined by an internal
1391definition is local to the <body>. That is, <variable> is bound rather
1392than assigned, and the region of the binding is the entire <body>. For
1393example,
1394
1395 (let ((x 5))
1396   (define foo (lambda (y) (bar x y)))
1397   (define bar (lambda (a b) (+ (* a b) a)))
1398   (foo (+ x 3)))                        ===>  45
1399
1400A <body> containing internal definitions can always be converted into
1401a completely equivalent letrec expression. For example, the let
1402expression in the above example is equivalent to
1403
1404 (let ((x 5))
1405   (letrec ((foo (lambda (y) (bar x y)))
1406            (bar (lambda (a b) (+ (* a b) a))))
1407     (foo (+ x 3))))
1408
1409Just as for the equivalent letrec expression, it must be possible to
1410evaluate each <expression> of every internal definition in a <body>
1411without assigning or referring to the value of any <variable> being
1412defined.
1413
1414Wherever an internal definition may occur (begin <definition1> ...) is
1415equivalent to the sequence of definitions that form the body of the
1416begin.
1417
1418CHICKEN extends the R7RS semantics by allowing internal definitions
1419everywhere, and not only at the beginning of a body. A set of internal
1420definitions is equivalent to a {{letrec}} form enclosing all following
1421expressions in the body:
1422
1423 (let ((foo 123))
1424   (bar)
1425   (define foo 456)
1426   (baz foo) )
1427
1428expands into
1429
1430 (let ((foo 123))
1431   (bar)
1432   (letrec ((foo 456))
1433     (baz foo) ) )
1434
1435Local sequences of {{define-syntax}} forms are translated into
1436equivalent {{letrec-syntax}} forms that enclose the following forms as
1437the body of the expression.
1438
1439===  Multiple-value definitions
1440
1441Another kind of definition is provided by define-values, which creates multiple
1442definitions from a single expression returning multiple values. It is allowed
1443wherever define is allowed.
1444
1445<macro>(define-values <formals> <expression>)</macro>
1446
1447It is an error if a variable appears more than once in the set of <formals>.
1448
1449Semantics: <Expression> is evaluated, and the <formals> are bound to the return
1450values in the same way that the <formals> in a lambda expression are matched to
1451the arguments in a procedure call.
1452
1453    (define-values (x y) (exact-integer-sqrt 17))
1454    (list x y)  ==> (4 1)
1455
1456    (let ()
1457      (define-values (x y) (values 1 2))
1458      (+ x y))      ==> 3
1459
1460=== Syntax definitions
1461
1462Syntax definitions are valid only at the top level of a
1463<program>. They have the following form:
1464
1465<macro>(define-syntax <keyword> <transformer spec>)</macro>
1466
1467{{<Keyword>}} is an identifier, and the {{<transformer spec>}} should
1468be an instance of {{syntax-rules}}.  Note that CHICKEN also supports
1469{{er-macro-transformer}} and {{ir-macro-transformer}} here.  For more
1470information see [[Module (chicken syntax)|the (chicken syntax) module]].
1471
1472The top-level syntactic environment is extended by binding the
1473<keyword> to the specified transformer.
1474
1475In standard Scheme, there is no define-syntax analogue of internal
1476definitions in, but CHICKEN allows these as an extension to the
1477standard.  This means {{define-syntax}} may be used to define local
1478macros that are visible throughout the rest of the body in which the
1479definition occurred, i.e.
1480
1481  (let ()
1482    ...
1483    (define-syntax foo ...)
1484    (define-syntax bar ...)
1485    ...)
1486
1487is expanded into
1488
1489  (let ()
1490    ...
1491    (letrec-syntax ((foo ...) (bar ...))
1492      ...) )
1493
1494{{syntax-rules}} supports [[http://srfi.schemers.org/srfi-46/|SRFI-46]]
1495in allowing the ellipsis identifier to be user-defined by passing it as the first
1496argument to the {{syntax-rules}} form. Also, "tail" patterns of the form
1497
1498  (syntax-rules ()
1499    ((_ (a b ... c) 
1500      ...
1501
1502are supported.
1503
1504The effect of destructively modifying the s-expression passed to a
1505transformer procedure is undefined.
1506
1507Although macros may expand into definitions and syntax definitions in
1508any context that permits them, it is an error for a definition or
1509syntax definition to shadow a syntactic keyword whose meaning is
1510needed to determine whether some form in the group of forms that
1511contains the shadowing definition is in fact a definition, or, for
1512internal definitions, is needed to determine the boundary between the
1513group and the expressions that follow the group. For example, the
1514following are errors:
1515
1516 (define define 3)
1517
1518 (begin (define begin list))
1519
1520 (let-syntax
1521   ((foo (syntax-rules ()
1522           ((foo (proc args ...) body ...)
1523            (define proc
1524              (lambda (args ...)
1525                body ...))))))
1526   (let ((x 3))
1527     (foo (plus x y) (+ x y))
1528     (define foo x)
1529     (plus foo x)))
1530
1531=== Record-type definitions
1532
1533Record-type definitions are used to introduce new data types, called record
1534types. Like other definitions, they can appear either at the outermost level or
1535in a body. The values of a record type are called records and are aggregations
1536of zero or more fields, each of which holds a single location. A predicate, a
1537constructor, and field accessors and mutators are defined for each record type.
1538
1539<macro>(define-record-type <name> <constructor> <pred> <field> ...)</macro>
1540
1541Syntax: <name> and <pred> are identifiers. The <constructor> is of the form
1542{{(<constructor name> <field name> ...)}} and each <field> is either of the form 
1543{{(<field name> <accessor name>)}} or of the form {{(<field name> <accessor name> <modifier name>)}}. It is an error for the same identifier to occur more than once
1544as a field name. It is also an error for the same identifier to occur more than
1545once as an accessor or mutator name.
1546
1547The define-record-type construct is generative: each use creates a new record
1548type that is distinct from all existing types, including Scheme’s predefined
1549types and other record types — even record types of the same name or structure.
1550
1551An instance of define-record-type is equivalent to the following definitions:
1552
1553*   <name> is bound to a representation of the record type itself. This may be
1554    a run-time object or a purely syntactic representation. The representation
1555    is not utilized in this report, but it serves as a means to identify the
1556    record type for use by further language extensions.
1557
1558*   <constructor name> is bound to a procedure that takes as many arguments as
1559    there are <field name>s in the {{(<constructor name> ...)}} subexpression and
1560    returns a new record of type <name>. Fields whose names are listed with
1561    <constructor name> have the corresponding argument as their initial value.
1562    The initial values of all other fields are unspecified. It is an error for
1563    a field name to appear in <constructor> but not as a <field name>.
1564
1565*   <pred> is bound to a predicate that returns #t when given a value returned
1566    by the procedure bound to <constructor name> and #f for everything else.
1567
1568*   Each <accessor name> is bound to a procedure that takes a record of type
1569    <name> and returns the current value of the corresponding field. It is an
1570    error to pass an accessor a value which is not a record of the appropriate
1571    type.
1572
1573*   Each <modifier name> is bound to a procedure that takes a record of type
1574    <name> and a value which becomes the new value of the corresponding field;
1575    an unspecified value is returned. It is an error to pass a modifier a first
1576    argument which is not a record of the appropriate type.
1577
1578For instance, the following record-type definition
1579
1580    (define-record-type <pare>
1581      (kons x y)
1582      pare?
1583      (x kar set-kar!)
1584      (y kdr))
1585
1586defines kons to be a constructor, kar and kdr to be accessors, set-kar! to be a
1587modifier, and pare? to be a predicate for instances of <pare>.
1588
1589    (pare? (kons 1 2))         ⟹ #t
1590      (pare? (cons 1 2))         ⟹ #f
1591      (kar (kons 1 2))           ⟹ 1
1592      (kdr (kons 1 2))           ⟹ 2
1593      (let ((k (kons 1 2)))
1594        (set-kar! k 3)
1595        (kar k))                 ⟹ 3
1596
1597=== Libraries
1598
1599Libraries provide a way to organize Scheme programs into reusable parts with
1600explicitly defined interfaces to the rest of the program. This section defines
1601the notation and semantics for libraries.
1602
1603====  Library Syntax
1604
1605A library definition takes the following form:
1606
1607<macro>(define-library <library name> <library declaration> ...)</macro>
1608
1609<library name> is a list whose members are identifiers and exact non-negative
1610integers. It is used to identify the library uniquely when importing from other
1611programs or libraries. Libraries whose first identifier is scheme are reserved
1612for use by this report and future versions of this report. Libraries whose
1613first identifier is srfi are reserved for libraries implementing Scheme
1614Requests for Implementation. It is inadvisable, but not an error, for
1615identifiers in library names to contain any of the characters | \ ? * < " : > +
1616[ ] / or control characters after escapes are expanded.
1617
1618A <library declaration> is any of:
1619
1620*   {{(export <export spec> ...)}}
1621
1622*   {{(import <import set> ...)}}
1623
1624*   {{(begin <command or definition> ...)}}
1625
1626*   {{(include <filename[1]> <filename[2]> ...)}}
1627
1628*   {{(include-ci <filename[1]> <filename[2]> ...)}}
1629
1630*   {{(include-library-declarations <filename[1]> <filename[2]> ...)}}
1631
1632*   {{(cond-expand <ce-clause[1]> <ce-clause[2]> ...}}
1633
1634An export declaration specifies a list of identifiers which can be made visible
1635to other libraries or programs. An <export spec> takes one of the following
1636forms:
1637
1638* <identifier>
1639
1640* {{(rename <identifier[1]> <identifier[2]>)}}
1641
1642In an <export spec>, an <identifier> names a single binding defined within or
1643imported into the library, where the external name for the export is the same
1644as the name of the binding within the library. A {{rename}} spec exports the
1645binding defined within or imported into the library and named by <identifier
1646[1]> in each {{(<identifier[1]> <identifier[2]>)}} pairing, using <identifier[2]>
1647as the external name.
1648
1649An import declaration provides a way to import the identifiers exported by
1650another library.
1651
1652The {{begin}}, {{include}}, and {{include}}-ci declarations are used to specify the body of
1653the library. They have the same syntax and semantics as the corresponding
1654expression types. This form of begin is analogous to, but not the same as, the
1655two types of begin defined in section 4.2.3.
1656
1657The {{include-library-declarations}} declaration is similar to {{include}} except that
1658the contents of the file are spliced directly into the current library
1659definition. This can be used, for example, to share the same export declaration
1660among multiple libraries as a simple form of library interface.
1661
1662The {{cond-expand}} declaration has the same syntax and semantics as the 
1663{{cond-expand}} expression type, except that it expands to spliced-in library
1664declarations rather than expressions enclosed in begin.
1665
1666One possible implementation of libraries is as follows: After all {{cond-expand}}
1667library declarations are expanded, a new environment is constructed for the
1668library consisting of all imported bindings. The expressions from all begin, 
1669{{include}} and {{include-ci}} library declarations are expanded in that environment in
1670the order in which they occur in the library. Alternatively, {{cond-expand}} and 
1671{{import}} declarations may be processed in left to right order interspersed with
1672the processing of other declarations, with the environment growing as imported
1673bindings are added to it by each import declaration.
1674
1675When a library is loaded, its expressions are executed in textual order. If a
1676library’s definitions are referenced in the expanded form of a program or
1677library body, then that library must be loaded before the expanded program or
1678library body is evaluated. This rule applies transitively. If a library is
1679imported by more than one program or library, it may possibly be loaded
1680additional times.
1681
1682Similarly, during the expansion of a library (foo), if any syntax keywords
1683imported from another library (bar) are needed to expand the library, then the
1684library (bar) must be expanded and its syntax definitions evaluated before the
1685expansion of (foo).
1686
1687
1688== Standard procedures
1689
1690This chapter describes Scheme's built-in procedures. The initial (or
1691"top level") Scheme environment starts out with a number of variables
1692bound to locations containing useful values, most of which are
1693primitive procedures that manipulate data. For example, the variable
1694abs is bound to (a location initially containing) a procedure of one
1695argument that computes the absolute value of a number, and the variable
1696+ is bound to a procedure that computes sums. Built-in procedures that
1697can easily be written in terms of other built-in procedures are
1698identified as "library procedures".
1699
1700A program may use a top-level definition to bind any variable. It may
1701subsequently alter any such binding by an assignment (see
1702[[#assignments|assignments]], above). These operations do
1703not modify the behavior of Scheme's built-in procedures. Altering any
1704top-level binding that has not been introduced by a definition has an
1705unspecified effect on the behavior of the built-in procedures.
1706
1707=== Equivalence predicates
1708
1709A predicate is a procedure that always returns a boolean value (#t or #f).
1710An equivalence predicate is the computational analogue of a
1711mathematical equivalence relation (it is symmetric, reflexive, and
1712transitive). Of the equivalence predicates described in this section,
1713eq? is the finest or most discriminating, and equal? is the coarsest.
1714eqv? is slightly less discriminating than eq?.
1715
1716<procedure>(eqv? obj[1] obj[2])</procedure><br>
1717
1718The eqv? procedure defines a useful equivalence relation on objects.
1719Briefly, it returns #t if obj[1] and obj[2] should normally be regarded
1720as the same object. This relation is left slightly open to
1721interpretation, but the following partial specification of eqv? holds
1722for all implementations of Scheme.
1723
1724The eqv? procedure returns #t if:
1725
1726*   obj[1] and obj[2] are both #t or both #f.
1727
1728*   obj[1] and obj[2] are both symbols and
1729
1730    (string=? (symbol->string obj1)
1731              (symbol->string obj2))
1732                ===>  #t
1733
1734Note: This assumes that neither obj[1] nor obj[2] is an "uninterned
1735symbol" as alluded to in the section on [[#symbols|symbols]]. This
1736report does not presume to specify the behavior of eqv? on
1737implementation-dependent extensions.
1738
1739*   obj[1] and obj[2] are both numbers, are numerically equal (see =,
1740    under [[#numerical-operations|numerical operations]]), and are
1741    either both exact or both inexact.
1742
1743*   obj[1] and obj[2] are both characters and are the same character
1744    according to the char=? procedure (see "[[#characters|characters]]").
1745
1746*   both obj[1] and obj[2] are the empty list.
1747
1748*   obj[1] and obj[2] are pairs, vectors, or strings that denote the
1749    same locations in the store.
1750
1751*   obj[1] and obj[2] are procedures whose location tags are equal
1752    (see "[[#procedures|procedures]]").
1753
1754The eqv? procedure returns #f if:
1755
1756*   obj[1] and obj[2] are of different types.
1757
1758*   one of obj[1] and obj[2] is #t but the other is #f.
1759
1760*   obj[1] and obj[2] are symbols but
1761
1762    (string=? (symbol->string obj[1])
1763              (symbol->string obj[2]))
1764                ===>  #f
1765
1766*   one of obj[1] and obj[2] is an exact number but the other is an
1767    inexact number.
1768
1769*   obj[1] and obj[2] are numbers for which the = procedure returns #f.
1770
1771*   obj[1] and obj[2] are characters for which the char=? procedure
1772    returns #f.
1773
1774*   one of obj[1] and obj[2] is the empty list but the other is not.
1775
1776*   obj[1] and obj[2] are pairs, vectors, or strings that denote
1777    distinct locations.
1778
1779*   obj[1] and obj[2] are procedures that would behave differently
1780    (return different value(s) or have different side effects) for some
1781    arguments.
1782
1783 (eqv? 'a 'a)                             ===>  #t
1784 (eqv? 'a 'b)                             ===>  #f
1785 (eqv? 2 2)                               ===>  #t
1786 (eqv? '() '())                           ===>  #t
1787 (eqv? 100000000 100000000)               ===>  #t
1788 (eqv? (cons 1 2) (cons 1 2))             ===>  #f
1789 (eqv? (lambda () 1)
1790       (lambda () 2))                     ===>  #f
1791 (eqv? #f 'nil)                           ===>  #f
1792 (let ((p (lambda (x) x)))
1793   (eqv? p p))                            ===>  #t
1794
1795The following examples illustrate cases in which the above rules do not
1796fully specify the behavior of eqv?. All that can be said about such
1797cases is that the value returned by eqv? must be a boolean.
1798
1799 (eqv? "" "")                     ===>  unspecified
1800 (eqv? '#() '#())                 ===>  unspecified
1801 (eqv? (lambda (x) x)
1802       (lambda (x) x))            ===>  unspecified
1803 (eqv? (lambda (x) x)
1804       (lambda (y) y))            ===>  unspecified
1805
1806The next set of examples shows the use of eqv? with procedures that
1807have local state. Gen-counter must return a distinct procedure every
1808time, since each procedure has its own internal counter. Gen-loser,
1809however, returns equivalent procedures each time, since the local state
1810does not affect the value or side effects of the procedures.
1811
1812 (define gen-counter
1813   (lambda ()
1814     (let ((n 0))
1815       (lambda () (set! n (+ n 1)) n))))
1816 (let ((g (gen-counter)))
1817   (eqv? g g))                   ===>  #t
1818 (eqv? (gen-counter) (gen-counter))
1819                                 ===>  #f
1820 (define gen-loser
1821   (lambda ()
1822     (let ((n 0))
1823       (lambda () (set! n (+ n 1)) 27))))
1824 (let ((g (gen-loser)))
1825   (eqv? g g))                   ===>  #t
1826 (eqv? (gen-loser) (gen-loser))
1827                                 ===>  unspecified
1828 
1829 (letrec ((f (lambda () (if (eqv? f g) 'both 'f)))
1830          (g (lambda () (if (eqv? f g) 'both 'g))))
1831   (eqv? f g))
1832                                 ===>  unspecified
1833 
1834 (letrec ((f (lambda () (if (eqv? f g) 'f 'both)))
1835          (g (lambda () (if (eqv? f g) 'g 'both))))
1836   (eqv? f g))
1837                                 ===>  #f
1838
1839Since it is an error to modify constant objects (those returned by
1840literal expressions), implementations are permitted, though not
1841required, to share structure between constants where appropriate. Thus
1842the value of eqv? on constants is sometimes implementation-dependent.
1843
1844 (eqv? '(a) '(a))                         ===>  unspecified
1845 (eqv? "a" "a")                           ===>  unspecified
1846 (eqv? '(b) (cdr '(a b)))                 ===>  unspecified
1847 (let ((x '(a)))
1848   (eqv? x x))                            ===>  #t
1849
1850Rationale:   The above definition of eqv? allows implementations
1851latitude in their treatment of procedures and literals:
1852implementations are free either to detect or to fail to detect that
1853two procedures or two literals are equivalent to each other, and
1854can decide whether or not to merge representations of equivalent
1855objects by using the same pointer or bit pattern to represent both.
1856
1857<procedure>(eq? obj[1] obj[2])</procedure><br>
1858
1859Eq? is similar to eqv? except that in some cases it is capable of
1860discerning distinctions finer than those detectable by eqv?.
1861
1862Eq? and eqv? are guaranteed to have the same behavior on symbols,
1863booleans, the empty list, pairs, procedures, and non-empty strings and
1864vectors. Eq?'s behavior on numbers and characters is
1865implementation-dependent, but it will always return either true or
1866false, and will return true only when eqv? would also return true. Eq?
1867may also behave differently from eqv? on empty vectors and empty
1868strings.
1869
1870 (eq? 'a 'a)                             ===>  #t
1871 (eq? '(a) '(a))                         ===>  unspecified
1872 (eq? (list 'a) (list 'a))               ===>  #f
1873 (eq? "a" "a")                           ===>  unspecified
1874 (eq? "" "")                             ===>  unspecified
1875 (eq? '() '())                           ===>  #t
1876 (eq? 2 2)                               ===>  unspecified
1877 (eq? #\A #\A)                           ===>  unspecified
1878 (eq? car car)                           ===>  #t
1879 (let ((n (+ 2 3)))
1880   (eq? n n))              ===>  unspecified
1881 (let ((x '(a)))
1882   (eq? x x))              ===>  #t
1883 (let ((x '#()))
1884   (eq? x x))              ===>  #t
1885 (let ((p (lambda (x) x)))
1886   (eq? p p))              ===>  #t
1887
1888Rationale:   It will usually be possible to implement eq? much more
1889efficiently than eqv?, for example, as a simple pointer comparison
1890instead of as some more complicated operation. One reason is that
1891it may not be possible to compute eqv? of two numbers in constant
1892time, whereas eq? implemented as pointer comparison will always
1893finish in constant time. Eq? may be used like eqv? in applications
1894using procedures to implement objects with state since it obeys the
1895same constraints as eqv?.
1896
1897<procedure>(equal? obj[1] obj[2])</procedure><br>
1898
1899Equal? recursively compares the contents of pairs, vectors, and
1900strings, applying eqv? on other objects such as numbers and symbols. A
1901rule of thumb is that objects are generally equal? if they print the
1902same. Equal? may fail to terminate if its arguments are circular data
1903structures.
1904
1905 (equal? 'a 'a)                          ===>  #t
1906 (equal? '(a) '(a))                      ===>  #t
1907 (equal? '(a (b) c)
1908         '(a (b) c))                     ===>  #t
1909 (equal? "abc" "abc")                    ===>  #t
1910 (equal? 2 2)                            ===>  #t
1911 (equal? (make-vector 5 'a)
1912         (make-vector 5 'a))             ===>  #t
1913 (equal? (lambda (x) x)
1914         (lambda (y) y))          ===>  unspecified
1915
1916=== Numbers
1917
1918Numerical computation has traditionally been neglected by the Lisp
1919community. Until Common Lisp there was no carefully thought out
1920strategy for organizing numerical computation, and with the exception
1921of the MacLisp system [20] little effort was made to execute numerical
1922code efficiently. This report recognizes the excellent work of the
1923Common Lisp committee and accepts many of their recommendations. In
1924some ways this report simplifies and generalizes their proposals in a
1925manner consistent with the purposes of Scheme.
1926
1927It is important to distinguish between the mathematical numbers, the
1928Scheme numbers that attempt to model them, the machine representations
1929used to implement the Scheme numbers, and notations used to write
1930numbers. This report uses the types number, complex, real, rational,
1931and integer to refer to both mathematical numbers and Scheme numbers.
1932Machine representations such as fixed point and floating point are
1933referred to by names such as fixnum and flonum.
1934
1935==== Numerical types
1936
1937Mathematically, numbers may be arranged into a tower of subtypes in
1938which each level is a subset of the level above it:
1939
1940    number
1941    complex
1942    real
1943    rational
1944    integer
1945
1946For example, 3 is an integer. Therefore 3 is also a rational, a real,
1947and a complex. The same is true of the Scheme numbers that model 3. For
1948Scheme numbers, these types are defined by the predicates number?,
1949complex?, real?, rational?, and integer?.
1950
1951There is no simple relationship between a number's type and its
1952representation inside a computer. Although most implementations of
1953Scheme will offer at least two different representations of 3, these
1954different representations denote the same integer.
1955
1956Scheme's numerical operations treat numbers as abstract data, as
1957independent of their representation as possible. Although an
1958implementation of Scheme may use fixnum, flonum, and perhaps other
1959representations for numbers, this should not be apparent to a casual
1960programmer writing simple programs.
1961
1962It is necessary, however, to distinguish between numbers that are
1963represented exactly and those that may not be. For example, indexes
1964into data structures must be known exactly, as must some polynomial
1965coefficients in a symbolic algebra system. On the other hand, the
1966results of measurements are inherently inexact, and irrational numbers
1967may be approximated by rational and therefore inexact approximations.
1968In order to catch uses of inexact numbers where exact numbers are
1969required, Scheme explicitly distinguishes exact from inexact numbers.
1970This distinction is orthogonal to the dimension of type.
1971
1972==== Exactness
1973
1974Scheme numbers are either exact or inexact. A number is exact if it was
1975written as an exact constant or was derived from exact numbers using
1976only exact operations. A number is inexact if it was written as an
1977inexact constant, if it was derived using inexact ingredients, or if it
1978was derived using inexact operations. Thus inexactness is a contagious
1979property of a number. If two implementations produce exact results for
1980a computation that did not involve inexact intermediate results, the
1981two ultimate results will be mathematically equivalent. This is
1982generally not true of computations involving inexact numbers since
1983approximate methods such as floating point arithmetic may be used, but
1984it is the duty of each implementation to make the result as close as
1985practical to the mathematically ideal result.
1986
1987Rational operations such as + should always produce exact results when
1988given exact arguments. If the operation is unable to produce an exact
1989result, then it may either report the violation of an implementation
1990restriction or it may silently coerce its result to an inexact value.
1991See [[#implementation-restrictions|the next section]].
1992
1993With the exception of inexact->exact, the operations described in this
1994section must generally return inexact results when given any inexact
1995arguments. An operation may, however, return an exact result if it can
1996prove that the value of the result is unaffected by the inexactness of
1997its arguments. For example, multiplication of any number by an exact
1998zero may produce an exact zero result, even if the other argument is
1999inexact.
2000
2001==== Implementation restrictions
2002
2003Implementations of Scheme are not required to implement the whole
2004tower of subtypes given under "[[#Numerical types|Numerical types]]",
2005but they must implement a coherent subset consistent with both the
2006purposes of the implementation and the spirit of the Scheme
2007language. For example, an implementation in which all numbers are real
2008may still be quite useful.
2009
2010Implementations may also support only a limited range of numbers of any
2011type, subject to the requirements of this section. The supported range
2012for exact numbers of any type may be different from the supported range
2013for inexact numbers of that type. For example, an implementation that
2014uses flonums to represent all its inexact real numbers may support a
2015practically unbounded range of exact integers and rationals while
2016limiting the range of inexact reals (and therefore the range of inexact
2017integers and rationals) to the dynamic range of the flonum format.
2018Furthermore the gaps between the representable inexact integers and
2019rationals are likely to be very large in such an implementation as the
2020limits of this range are approached.
2021
2022An implementation of Scheme must support exact integers throughout the
2023range of numbers that may be used for indexes of lists, vectors, and
2024strings or that may result from computing the length of a list, vector,
2025or string. The length, vector-length, and string-length procedures must
2026return an exact integer, and it is an error to use anything but an
2027exact integer as an index. Furthermore any integer constant within the
2028index range, if expressed by an exact integer syntax, will indeed be
2029read as an exact integer, regardless of any implementation restrictions
2030that may apply outside this range. Finally, the procedures listed below
2031will always return an exact integer result provided all their arguments
2032are exact integers and the mathematically expected result is
2033representable as an exact integer within the implementation:
2034
2035 -                     *
2036 +                     abs
2037 ceiling               denominator
2038 exact-integer-sqrt    expt
2039 floor                 floor/
2040 floor-quotient        floor-remainder
2041 gcd                   lcm
2042 max                   min
2043 modulo                numerator
2044 quotient              rationalize
2045 remainder             round
2046 square                truncate
2047 truncate/             truncate-quotient
2048 truncate-remainder
2049
2050CHICKEN follows the IEEE 32-bit and 64-bit floating point
2051standards on all supported platforms.
2052
2053It is the programmer’s responsibility to avoid using inexact number objects
2054with magnitude or significand too large to be represented in the
2055implementation.
2056
2057In addition, implementations may distinguish special numbers called positive
2058infinity, negative infinity, NaN, and negative zero.
2059
2060Positive infinity is regarded as an inexact real (but not rational) number that
2061represents an indeterminate value greater than the numbers represented by all
2062rational numbers. Negative infinity is regarded as an inexact real (but not
2063rational) number that represents an indeterminate value less than the numbers
2064represented by all rational numbers.
2065
2066Adding or multiplying an infinite value by any finite real value results in an
2067appropriately signed infinity; however, the sum of positive and negative
2068infinities is a NaN. Positive infinity is the reciprocal of zero, and negative
2069infinity is the reciprocal of negative zero. The behavior of the transcendental
2070functions is sensitive to infinity in accordance with IEEE 754.
2071
2072A NaN is regarded as an inexact real (but not rational) number so indeterminate
2073that it might represent any real value, including positive or negative
2074infinity, and might even be greater than positive infinity or less than
2075negative infinity. An implementation that does not support non-real numbers may
2076use NaN to represent non-real values like (sqrt -1.0) and (asin 2.0).
2077
2078A NaN always compares false to any number, including a NaN. An arithmetic
2079operation where one operand is NaN returns NaN, unless the implementation can
2080prove that the result would be the same if the NaN were replaced by any
2081rational number. Dividing zero by zero results in NaN unless both zeros are
2082exact.
2083
2084Negative zero is an inexact real value written -0.0 and is distinct (in the
2085sense of eqv?) from 0.0. A Scheme implementation is not required to distinguish
2086negative zero. If it does, however, the behavior of the transcendental
2087functions is sensitive to the distinction in accordance with IEEE 754.
2088Specifically, in a Scheme implementing both complex numbers and negative zero,
2089the branch cut of the complex logarithm function is such that (imag-part (log
2090-1.0-0.0i)) is −π rather than π.
2091
2092Furthermore, the negation of negative zero is ordinary zero and vice versa.
2093This implies that the sum of two or more negative zeros is negative, and the
2094result of subtracting (positive) zero from a negative zero is likewise
2095negative. However, numerical comparisons treat negative zero as equal to zero.
2096
2097Note that both the real and the imaginary parts of a complex number can be
2098infinities, NaNs, or negative zero.
2099
2100
2101==== Syntax of numerical constants
2102
2103For a complete formal description of the syntax of the written
2104representations for numbers, see the R7RS report. Note that case is
2105not significant in numerical constants.
2106
2107A number may be written in binary, octal, decimal, or hexadecimal by
2108the use of a radix prefix. The radix prefixes are #b (binary), #o
2109(octal), #d (decimal), and #x (hexadecimal). With no radix prefix, a
2110number is assumed to be expressed in decimal.
2111
2112A numerical constant may be specified to be either exact or inexact by
2113a prefix. The prefixes are #e for exact, and #i for inexact. An
2114exactness prefix may appear before or after any radix prefix that is
2115used. If the written representation of a number has no exactness
2116prefix, the constant may be either inexact or exact. It is inexact if
2117it contains a decimal point, an exponent, or a "#" character in the
2118place of a digit, otherwise it is exact. In systems with inexact
2119numbers of varying precisions it may be useful to specify the precision
2120of a constant. For this purpose, numerical constants may be written
2121with an exponent marker that indicates the desired precision of the
2122inexact representation. The letters s, f, d, and l specify the use of
2123short, single, double, and long precision, respectively. (When fewer
2124than four internal inexact representations exist, the four size
2125specifications are mapped onto those available. For example, an
2126implementation with two internal representations may map short and
2127single together and long and double together.) In addition, the
2128exponent marker e specifies the default precision for the
2129implementation. The default precision has at least as much precision as
2130double, but implementations may wish to allow this default to be set by
2131the user.
2132
2133 3.14159265358979F0
2134         Round to single --- 3.141593
2135 0.6L0
2136         Extend to long --- .600000000000000
2137
2138==== Numerical operations
2139
2140The numerical routines described below have argument restrictions,
2141which are encoded in the naming conventions of the arguments as
2142given in the procedure's signature.  The conventions are as follows:
2143
2144; {{obj}} : any object
2145; {{list, list1, ... listj, ...	list}} : (see "[[#pairs-and-lists|Pairs and lists]]" below)
2146; {{z, z1, ... zj, ...}} : complex number
2147; {{x, x1, ... xj, ...}} : real number
2148; {{y, y1, ... yj, ...}} : real number
2149; {{q, q1, ... qj, ...}} : rational number 
2150; {{n, n1, ... nj, ...}} : integer
2151; {{k, k1, ... kj, ...}} : exact non-negative integer
2152
2153The examples used in this section assume that any
2154numerical constant written using an exact notation is indeed
2155represented as an exact number. Some examples also assume that certain
2156numerical constants written using an inexact notation can be
2157represented without loss of accuracy; the inexact constants were chosen
2158so that this is likely to be true in implementations that use flonums
2159to represent inexact numbers.
2160
2161<procedure>(number? obj)</procedure><br>
2162<procedure>(complex? obj)</procedure><br>
2163<procedure>(real? obj)</procedure><br>
2164<procedure>(rational? obj)</procedure><br>
2165<procedure>(integer? obj)</procedure><br>
2166
2167These numerical type predicates can be applied to any kind of argument,
2168including non-numbers. They return #t if the object is of the named
2169type, and otherwise they return #f. In general, if a type predicate is
2170true of a number then all higher type predicates are also true of that
2171number. Consequently, if a type predicate is false of a number, then
2172all lower type predicates are also false of that number. If z is an
2173inexact complex number, then (real? z) is true if and only if (zero?
2174(imag-part z)) is true. If x is an inexact real number, then (integer?
2175x) is true if and only if (= x (round x)).
2176
2177 (complex? 3+4i)                 ===>  #t
2178 (complex? 3)                    ===>  #t
2179 (real? 3)                       ===>  #t
2180 (real? -2.5+0.0i)               ===>  #t
2181 (real? #e1e10)                  ===>  #t
2182 (rational? 6/10)                ===>  #t
2183 (rational? 6/3)                 ===>  #t
2184 (integer? 3+0i)                 ===>  #t
2185 (integer? 3.0)                  ===>  #t
2186 (integer? 8/4)                  ===>  #t
2187
2188Note:   The behavior of these type predicates on inexact numbers is
2189unreliable, since any inaccuracy may affect the result.
2190
2191Note:   In many implementations the rational? procedure will be the
2192same as real?, and the complex? procedure will be the same as
2193number?, but unusual implementations may be able to represent some
2194irrational numbers exactly or may extend the number system to
2195support some kind of non-complex numbers.
2196
2197<procedure>(exact? z)</procedure><br>
2198<procedure>(inexact? z)</procedure><br>
2199
2200These numerical predicates provide tests for the exactness of a
2201quantity. For any Scheme number, precisely one of these predicates is
2202true.
2203
2204<procedure>(exact-integer? z)</procedure>
2205
2206Returns #t if z is both exact and an integer; otherwise returns #f.
2207
2208 (exact-integer? 32)  ===> #t
2209 (exact-integer? 32.0)  ===> #f
2210 (exact-integer? 32/5)  ===> #f
2211
2212<procedure>(= z[1] z[2] z[3] ...)</procedure><br>
2213<procedure>(< x[1] x[2] x[3] ...)</procedure><br>
2214<procedure>(> x[1] x[2] x[3] ...)</procedure><br>
2215<procedure>(<= x[1] x[2] x[3] ...)</procedure><br>
2216<procedure>(>= x[1] x[2] x[3] ...)</procedure><br>
2217
2218These procedures return #t if their arguments are (respectively):
2219equal, monotonically increasing, monotonically decreasing,
2220monotonically nondecreasing, or monotonically nonincreasing.
2221
2222These predicates are required to be transitive.
2223
2224Note:   The traditional implementations of these predicates in
2225Lisp-like languages are not transitive.
2226
2227Note:   While it is not an error to compare inexact numbers using
2228these predicates, the results may be unreliable because a small
2229inaccuracy may affect the result; this is especially true of = and
2230zero?. When in doubt, consult a numerical analyst.
2231
2232<procedure>(zero? z)</procedure><br>
2233<procedure>(positive? x)</procedure><br>
2234<procedure>(negative? x)</procedure><br>
2235<procedure>(odd? n)</procedure><br>
2236<procedure>(even? n)</procedure><br>
2237
2238These numerical predicates test a number for a particular property,
2239returning #t or #f. See note above.
2240
2241<procedure>(max x[1] x[2] ...)</procedure><br>
2242<procedure>(min x[1] x[2] ...)</procedure><br>
2243
2244These procedures return the maximum or minimum of their arguments.
2245
2246 (max 3 4)                      ===>  4    ; exact
2247 (max 3.9 4)                    ===>  4.0  ; inexact
2248
2249Note:   If any argument is inexact, then the result will also be
2250inexact (unless the procedure can prove that the inaccuracy is not
2251large enough to affect the result, which is possible only in
2252unusual implementations). If min or max is used to compare numbers
2253of mixed exactness, and the numerical value of the result cannot be
2254represented as an inexact number without loss of accuracy, then the
2255procedure may report a violation of an implementation restriction.
2256
2257<procedure>(+ z[1] ...)</procedure><br>
2258<procedure>(* z[1] ...)</procedure><br>
2259
2260These procedures return the sum or product of their arguments.
2261
2262 (+ 3 4)                         ===>  7
2263 (+ 3)                           ===>  3
2264 (+)                             ===>  0
2265 (* 4)                           ===>  4
2266 (*)                             ===>  1
2267
2268<procedure>(- z[1] z[2])</procedure><br>
2269<procedure>(- z)</procedure><br>
2270<procedure>(- z[1] z[2] ...)</procedure><br>
2271<procedure>(/ z[1] z[2])</procedure><br>
2272<procedure>(/ z)</procedure><br>
2273<procedure>(/ z[1] z[2] ...)</procedure><br>
2274
2275With two or more arguments, these procedures return the difference or
2276quotient of their arguments, associating to the left. With one
2277argument, however, they return the additive or multiplicative inverse
2278of their argument.
2279
2280 (- 3 4)                         ===>  -1
2281 (- 3 4 5)                       ===>  -6
2282 (- 3)                           ===>  -3
2283 (/ 3 4 5)                       ===>  3/20
2284 (/ 3)                           ===>  1/3
2285
2286<procedure>(abs x)</procedure><br>
2287
2288Abs returns the absolute value of its argument.
2289
2290 (abs -7)                        ===>  7
2291
2292<procedure>(floor/ n[1] n[2])</procedure><br>
2293<procedure>(floor-quotient n[1] n[2])</procedure><br>
2294<procedure>(floor-remainder n[1] n[2])</procedure><br>
2295<procedure>(truncate/ n[1] n[2])</procedure><br>
2296<procedure>(truncate-quotient n[1] n[2])</procedure><br>
2297<procedure>(truncate-remainder n[1] n[2])</procedure><br>
2298
2299These procedures implement number-theoretic (integer) division. It is an error
2300if n[2] is zero. The procedures ending in / return two integers; the other
2301procedures return an integer. All the procedures compute a quotient n[q] and remainder
2302n[r] such that n[1] = n[2] * n[q] + n[r]. For each of the division operators, there are three procedures defined as
2303follows:
2304
2305 (<operator>/ n[1] n[2]) ==> n[q] n[r]
2306 (<operator>-quotient n[1] n[2]) ==> n[q]
2307 (<operator>-remainder n[1] n[2]) ==> n[r]
2308
2309The remainder n[r] is determined by the choice of integer n[q]: n[r] = n[1] − n[2] * n[q]. Each set of operators uses a different choice of n[q]:
2310
2311 floor    n[q] = ⌊n[1] / n[2]⌋
2312 truncate n[q] = runcate(n[1] / n[2])
2313
2314For any of the operators, and for integers n[1] and n[2] with n[2] not equal to 0,
2315
2316 (= n[1] (+ (* n[2] (<operator>-quotient n[1] n[2]))
2317         (<operator>-remainder n[1] n[2])))
2318         ==> #t
2319
2320provided all numbers involved in that computation are exact.
2321
2322Examples:
2323
2324 (floor/ 5 2)          ==> 2 1
2325 (floor/ -5 2)         ==> -3 1
2326 (floor/ 5 -2)         ==> -3 -1
2327 (floor/ -5 -2)        ==> 2 -1
2328 (truncate/ 5 2)       ==> 2 1
2329 (truncate/ -5 2)      ==> -2 -1
2330 (truncate/ 5 -2)      ==> -2 1
2331 (truncate/ -5 -2)     ==> 2 -1
2332 (truncate/ -5.0 -2)   ==> 2.0 -1.0
2333
2334<procedure>(quotient n[1] n[2])</procedure><br>
2335<procedure>(remainder n[1] n[2])</procedure><br>
2336<procedure>(modulo n[1] n[2])</procedure><br>
2337
2338These procedures implement number-theoretic (integer) division. n[2]
2339should be non-zero. All three procedures return integers. If n[1]/n[2]
2340is an integer:
2341
2342    (quotient n[1] n[2])           ===> n[1]/n[2]
2343    (remainder n[1] n[2])          ===> 0
2344    (modulo n[1] n[2])             ===> 0
2345
2346If n[1]/n[2] is not an integer:
2347
2348    (quotient n[1] n[2])           ===> n[q]
2349    (remainder n[1] n[2])          ===> n[r]
2350    (modulo n[1] n[2])             ===> n[m]
2351
2352where n[q] is n[1]/n[2] rounded towards zero, 0 < |n[r]| < |n[2]|, 0 <
2353|n[m]| < |n[2]|, n[r] and n[m] differ from n[1] by a multiple of n[2],
2354n[r] has the same sign as n[1], and n[m] has the same sign as n[2].
2355
2356From this we can conclude that for integers n[1] and n[2] with n[2] not
2357equal to 0,
2358
2359     (= n[1] (+ (* n[2] (quotient n[1] n[2]))
2360           (remainder n[1] n[2])))
2361                                         ===>  #t
2362
2363provided all numbers involved in that computation are exact.
2364
2365 (modulo 13 4)                   ===>  1
2366 (remainder 13 4)                ===>  1
2367 
2368 (modulo -13 4)                  ===>  3
2369 (remainder -13 4)               ===>  -1
2370 
2371 (modulo 13 -4)                  ===>  -3
2372 (remainder 13 -4)               ===>  1
2373 
2374 (modulo -13 -4)                 ===>  -1
2375 (remainder -13 -4)              ===>  -1
2376 
2377 (remainder -13 -4.0)            ===>  -1.0  ; inexact
2378
2379<procedure>(gcd n[1] ...)</procedure><br>
2380<procedure>(lcm n[1] ...)</procedure><br>
2381
2382These procedures return the greatest common divisor or least common
2383multiple of their arguments. The result is always non-negative.
2384
2385 (gcd 32 -36)                    ===>  4
2386 (gcd)                           ===>  0
2387 (lcm 32 -36)                    ===>  288
2388 (lcm 32.0 -36)                  ===>  288.0  ; inexact
2389 (lcm)                           ===>  1
2390
2391<procedure>(numerator q)</procedure><br>
2392<procedure>(denominator q)</procedure><br>
2393
2394These procedures return the numerator or denominator of their argument;
2395the result is computed as if the argument was represented as a fraction
2396in lowest terms. The denominator is always positive. The denominator of
23970 is defined to be 1.
2398
2399 (numerator (/ 6 4))            ===>  3
2400 (denominator (/ 6 4))          ===>  2
2401 (denominator
2402   (exact->inexact (/ 6 4)))    ===> 2.0
2403
2404<procedure>(floor x)</procedure><br>
2405<procedure>(ceiling x)</procedure><br>
2406<procedure>(truncate x)</procedure><br>
2407<procedure>(round x)</procedure><br>
2408
2409These procedures return integers. Floor returns the largest integer not
2410larger than x. Ceiling returns the smallest integer not smaller than x.
2411Truncate returns the integer closest to x whose absolute value is not
2412larger than the absolute value of x. Round returns the closest integer
2413to x, rounding to even when x is halfway between two integers.
2414
2415Rationale:   Round rounds to even for consistency with the default
2416rounding mode specified by the IEEE floating point standard.
2417
2418Note:   If the argument to one of these procedures is inexact, then
2419the result will also be inexact. If an exact value is needed, the
2420result should be passed to the inexact->exact procedure.
2421
2422 (floor -4.3)                  ===>  -5.0
2423 (ceiling -4.3)                ===>  -4.0
2424 (truncate -4.3)               ===>  -4.0
2425 (round -4.3)                  ===>  -4.0
2426 
2427 (floor 3.5)                   ===>  3.0
2428 (ceiling 3.5)                 ===>  4.0
2429 (truncate 3.5)                ===>  3.0
2430 (round 3.5)                   ===>  4.0  ; inexact
2431 
2432 (round 7/2)                   ===>  4    ; exact
2433 (round 7)                     ===>  7
2434
2435<procedure>(rationalize x y)</procedure><br>
2436
2437Rationalize returns the simplest rational number differing from x by no
2438more than y. A rational number r[1] is simpler than another rational
2439number r[2] if r[1] = p[1]/q[1] and r[2] = p[2]/q[2] (in lowest terms)
2440and |p[1]| < |p[2]| and |q[1]| < |q[2]|. Thus 3/5 is simpler than 4/7.
2441Although not all rationals are comparable in this ordering (consider 2/
24427 and 3/5) any interval contains a rational number that is simpler than
2443every other rational number in that interval (the simpler 2/5 lies
2444between 2/7 and 3/5). Note that 0 = 0/1 is the simplest rational of
2445all.
2446
2447 (rationalize
2448   (inexact->exact .3) 1/10)          ===> 1/3    ; exact
2449 (rationalize .3 1/10)                ===> #i1/3  ; inexact
2450
2451<procedure>(exp z)</procedure><br>
2452<procedure>(log z [z2])</procedure><br>
2453<procedure>(sin z)</procedure><br>
2454<procedure>(cos z)</procedure><br>
2455<procedure>(tan z)</procedure><br>
2456<procedure>(asin z)</procedure><br>
2457<procedure>(acos z)</procedure><br>
2458<procedure>(atan z)</procedure><br>
2459<procedure>(atan y x)</procedure><br>
2460
2461These procedures are part of every implementation that supports general
2462real numbers; they compute the usual transcendental functions. The Log
2463procedure computes the natural logarithm of z (not the base ten logarithm)
2464if a single argument is given, or the base-z2 logarithm of z1 if two arguments are
2465given.
2466Asin, acos, and atan compute arcsine (sin^-1), arccosine (cos^-1), and
2467arctangent (tan^-1), respectively. The two-argument variant of atan
2468computes (angle (make-rectangular x y)) (see below), even in
2469implementations that don't support general complex numbers.
2470
2471In general, the mathematical functions log, arcsine, arccosine, and
2472arctangent are multiply defined. The value of log z is defined to be
2473the one whose imaginary part lies in the range from -pi
2474(exclusive) to pi (inclusive). log 0 is undefined. With log
2475defined this way, the values of sin^-1 z, cos^-1 z, and tan^-1 z are
2476according to the following formulae:
2477
2478 sin^-1 z = - i log (i z + (1 - z^2)^1/2)
2479 
2480 cos^-1 z = pi / 2 - sin^-1 z
2481 
2482 tan^-1 z = (log (1 + i z) - log (1 - i z)) / (2 i)
2483
2484The above specification follows [27], which in turn cites [19]; refer
2485to these sources for more detailed discussion of branch cuts, boundary
2486conditions, and implementation of these functions. When it is possible
2487these procedures produce a real result from a real argument.
2488
2489<procedure>(square z)</procedure>
2490
2491Returns the square of z. This is equivalent to {{(* z z)}}-
2492
2493 (square 42)        ==> 1764
2494 (square 2.0)      ==> 4.0
2495
2496<procedure>(exact-integer-sqrt k)</procedure>
2497
2498Returns two non-negative exact integers s and r where k = s^2 + r and k < (s + 1)^2.
2499
2500 (exact-integer-sqrt 4)  ==> 2 0
2501 (exact-integer-sqrt 5)  ==> 2 1
2502
2503<procedure>(expt z[1] z[2])</procedure><br>
2504
2505Returns z[1] raised to the power z[2]. For z[1] != 0
2506
2507 z[1]^z[2] = e^z[2] log z[1]
2508
25090^z is 1 if z = 0 and 0 otherwise.
2510
2511<procedure>(exact z)</procedure><br>
2512<procedure>(inexact z)</procedure><br>
2513
2514The procedure {{inexact}}  returns an inexact representation of z. The value returned is the inexact number that is numerically closest to the
2515argument. For inexact arguments, the result is the same as the argument. For
2516exact complex numbers, the result is a complex number whose real and imaginary
2517parts are the result of applying inexact to the real and imaginary parts of the
2518argument, respectively. If an exact argument has no reasonably close inexact
2519equivalent (in the sense of =), then a violation of an implementation
2520restriction may be reported.
2521
2522The procedure {{exact}} returns an exact representation of z. The value returned is the exact number that is numerically closest to the
2523argument. For exact arguments, the result is the same as the argument. For
2524inexact non-integral real arguments, the implementation may return a rational
2525approximation, or may report an implementation violation. For inexact complex
2526arguments, the result is a complex number whose real and imaginary parts are
2527the result of applying exact to the real and imaginary parts of the argument,
2528respectively. If an inexact argument has no reasonably close exact equivalent,
2529(in the sense of =), then a violation of an implementation restriction may be
2530reported.
2531
2532==== Numerical input and output
2533
2534<procedure>(number->string z [radix])</procedure>
2535
2536Radix must be an exact integer.  The R7RS standard only requires
2537implementations to support 2, 8, 10, or 16, but CHICKEN allows any
2538radix between 2 and 36, inclusive (note: a bug in CHICKEN 5 currently 
2539limits the upper bound to 16).  If omitted, radix defaults to
254010. The procedure number->string takes a number and a radix and
2541returns as a string an external representation of the given number in
2542the given radix such that
2543
2544 (let ((number number)
2545       (radix radix))
2546   (eqv? number
2547         (string->number (number->string number
2548                                         radix)
2549                         radix)))
2550
2551is true. It is an error if no possible result makes this expression
2552true.
2553
2554If z is inexact, the radix is 10, and the above expression can be
2555satisfied by a result that contains a decimal point, then the result
2556contains a decimal point and is expressed using the minimum number of
2557digits (exclusive of exponent and trailing zeroes) needed to make the
2558above expression true [3, 5]; otherwise the format of the result is
2559unspecified.
2560
2561The result returned by number->string never contains an explicit radix
2562prefix.
2563
2564Note:   The error case can occur only when z is not a complex
2565number or is a complex number with a non-rational real or imaginary
2566part.
2567
2568Rationale:   If z is an inexact number represented using flonums,
2569and the radix is 10, then the above expression is normally
2570satisfied by a result containing a decimal point. The unspecified
2571case allows for infinities, NaNs, and non-flonum representations.
2572
2573As an extension to R7RS, CHICKEN supports reading and writing the
2574special IEEE floating-point numbers ''+nan'', ''+inf'' and ''-inf'',
2575as well as negative zero.
2576
2577<procedure>(string->number string)</procedure><br>
2578<procedure>(string->number string radix)</procedure><br>
2579
2580Returns a number of the maximally precise representation expressed by
2581the given string.  Radix must be an exact integer.  The R7RS standard
2582only requires implementations to support 2, 8, 10, or 16, but CHICKEN
2583allows any radix between 2 and 36, inclusive.  If supplied, radix is a
2584default radix that may be overridden by an explicit radix prefix in
2585string (e.g. "#o177"). If radix is not supplied, then the default
2586radix is 10. If string is not a syntactically valid notation for a
2587number, then string->number returns #f.
2588
2589 (string->number "100")                ===>  100
2590 (string->number "100" 16)             ===>  256
2591 (string->number "1e2")                ===>  100.0
2592 (string->number "15##")               ===>  1500.0
2593
2594Note:   The domain of string->number may be restricted by
2595implementations in the following ways. String->number is permitted
2596to return #f whenever string contains an explicit radix prefix. If
2597all numbers supported by an implementation are real, then string->
2598number is permitted to return #f whenever string uses the polar or
2599rectangular notations for complex numbers. If all numbers are
2600integers, then string->number may return #f whenever the fractional
2601notation is used. If all numbers are exact, then string->number may
2602return #f whenever an exponent marker or explicit exactness prefix
2603is used, or if a # appears in place of a digit. If all inexact
2604numbers are integers, then string->number may return #f whenever a
2605decimal point is used.
2606
2607=== Other data types
2608
2609This section describes operations on some of Scheme's non-numeric data
2610types: booleans, pairs, lists, symbols, characters, strings and
2611vectors.
2612
2613==== Booleans
2614
2615The standard boolean objects for true and false are written as #t and #f.
2616What really matters, though, are the objects that the Scheme
2617conditional expressions (if, cond, and, or, do) treat as true or false.
2618The phrase "a true value" (or sometimes just "true") means any
2619object treated as true by the conditional expressions, and the phrase
2620"a false value" (or "false") means any object treated as false by
2621the conditional expressions.
2622
2623Of all the standard Scheme values, only #f counts as false in
2624conditional expressions. Except for #f, all standard Scheme values,
2625including #t, pairs, the empty list, symbols, numbers, strings,
2626vectors, and procedures, count as true.
2627
2628Note:   Programmers accustomed to other dialects of Lisp should be
2629aware that Scheme distinguishes both #f and the empty list from the
2630symbol nil.
2631
2632Boolean constants evaluate to themselves, so they do not need to be
2633quoted in programs.
2634
2635 #t                ===>  #t
2636 #f                ===>  #f
2637 '#f               ===>  #f
2638
2639<procedure>(not obj)</procedure><br>
2640
2641Not returns #t if obj is false, and returns #f otherwise.
2642
2643 (not #t)           ===>  #f
2644 (not 3)            ===>  #f
2645 (not (list 3))     ===>  #f
2646 (not #f)           ===>  #t
2647 (not '())          ===>  #f
2648 (not (list))       ===>  #f
2649 (not 'nil)         ===>  #f
2650
2651<procedure>(boolean? obj)</procedure><br>
2652
2653Boolean? returns #t if obj is either #t or #f and returns #f otherwise.
2654
2655 (boolean? #f)                 ===>  #t
2656 (boolean? 0)                  ===>  #f
2657 (boolean? '())                ===>  #f
2658
2659<procedure>(boolean=? boolean[1] boolean[2] boolean[3] ...)</procedure>
2660
2661Returns #t if all the arguments are #t or all are #f.
2662
2663==== Pairs and lists
2664
2665A pair (sometimes called a dotted pair) is a record structure with two
2666fields called the car and cdr fields (for historical reasons). Pairs
2667are created by the procedure cons. The car and cdr fields are accessed
2668by the procedures car and cdr. The car and cdr fields are assigned by
2669the procedures set-car! and set-cdr!.
2670
2671Pairs are used primarily to represent lists. A list can be defined
2672recursively as either the empty list or a pair whose cdr is a list.
2673More precisely, the set of lists is defined as the smallest set X such
2674that
2675
2676*   The empty list is in X.
2677*   If list is in X, then any pair whose cdr field contains list is
2678    also in X.
2679
2680The objects in the car fields of successive pairs of a list are the
2681elements of the list. For example, a two-element list is a pair whose
2682car is the first element and whose cdr is a pair whose car is the
2683second element and whose cdr is the empty list. The length of a list is
2684the number of elements, which is the same as the number of pairs.
2685
2686The empty list is a special object of its own type (it is not a pair);
2687it has no elements and its length is zero.
2688
2689Note:   The above definitions imply that all lists have finite
2690length and are terminated by the empty list.
2691
2692The most general notation (external representation) for Scheme pairs is
2693the "dotted" notation (c[1] . c[2]) where c[1] is the value of the
2694car field and c[2] is the value of the cdr field. For example (4 . 5)
2695is a pair whose car is 4 and whose cdr is 5. Note that (4 . 5) is the
2696external representation of a pair, not an expression that evaluates to
2697a pair.
2698
2699A more streamlined notation can be used for lists: the elements of the
2700list are simply enclosed in parentheses and separated by spaces. The
2701empty list is written () . For example,
2702
2703 (a b c d e)
2704
2705and
2706
2707 (a . (b . (c . (d . (e . ())))))
2708
2709are equivalent notations for a list of symbols.
2710
2711A chain of pairs not ending in the empty list is called an improper
2712list. Note that an improper list is not a list. The list and dotted
2713notations can be combined to represent improper lists:
2714
2715 (a b c . d)
2716
2717is equivalent to
2718
2719 (a . (b . (c . d)))
2720
2721Whether a given pair is a list depends upon what is stored in the cdr
2722field. When the set-cdr! procedure is used, an object can be a list one
2723moment and not the next:
2724
2725 (define x (list 'a 'b 'c))
2726 (define y x)
2727 y                               ===>  (a b c)
2728 (list? y)                       ===>  #t
2729 (set-cdr! x 4)                  ===>  unspecified
2730 x                               ===>  (a . 4)
2731 (eqv? x y)                      ===>  #t
2732 y                               ===>  (a . 4)
2733 (list? y)                       ===>  #f
2734 (set-cdr! x x)                  ===>  unspecified
2735 (list? x)                       ===>  #f
2736
2737Within literal expressions and representations of objects read by the
2738read procedure, the forms '<datum>, `<datum>, ,<datum>, and ,@<datum>
2739denote two-element lists whose first elements are the symbols quote,
2740quasiquote, unquote, and unquote-splicing, respectively. The second
2741element in each case is <datum>. This convention is supported so that
2742arbitrary Scheme programs may be represented as lists. That is,
2743according to Scheme's grammar, every <expression> is also a <datum>.
2744Among other things, this permits the use of the read procedure to
2745parse Scheme programs.
2746
2747<procedure>(pair? obj)</procedure><br>
2748
2749Pair? returns #t if obj is a pair, and otherwise returns #f.
2750
2751 (pair? '(a . b))                ===>  #t
2752 (pair? '(a b c))                ===>  #t
2753 (pair? '())                     ===>  #f
2754 (pair? '#(a b))                 ===>  #f
2755
2756<procedure>(cons obj[1] obj[2])</procedure><br>
2757
2758Returns a newly allocated pair whose car is obj[1] and whose cdr is
2759obj[2]. The pair is guaranteed to be different (in the sense of eqv?)
2760from every existing object.
2761
2762 (cons 'a '())                   ===>  (a)
2763 (cons '(a) '(b c d))            ===>  ((a) b c d)
2764 (cons "a" '(b c))               ===>  ("a" b c)
2765 (cons 'a 3)                     ===>  (a . 3)
2766 (cons '(a b) 'c)                ===>  ((a b) . c)
2767
2768<procedure>(car pair)</procedure><br>
2769
2770Returns the contents of the car field of pair. Note that it is an error
2771to take the car of the empty list.
2772
2773 (car '(a b c))                  ===>  a
2774 (car '((a) b c d))              ===>  (a)
2775 (car '(1 . 2))                  ===>  1
2776 (car '())                       ===>  error
2777
2778<procedure>(cdr pair)</procedure><br>
2779
2780Returns the contents of the cdr field of pair. Note that it is an error
2781to take the cdr of the empty list.
2782
2783 (cdr '((a) b c d))              ===>  (b c d)
2784 (cdr '(1 . 2))                  ===>  2
2785 (cdr '())                       ===>  error
2786
2787<procedure>(set-car! pair obj)</procedure><br>
2788
2789Stores obj in the car field of pair. The value returned by set-car! is
2790unspecified.
2791
2792 (define (f) (list 'not-a-constant-list))
2793 (define (g) '(constant-list))
2794 (set-car! (f) 3)                     ===>  unspecified
2795 (set-car! (g) 3)                     ===>  error
2796
2797<procedure>(set-cdr! pair obj)</procedure><br>
2798
2799Stores obj in the cdr field of pair. The value returned by set-cdr! is
2800unspecified.
2801
2802<procedure>(null? obj)</procedure><br>
2803
2804Returns #t if obj is the empty list, otherwise returns #f.
2805
2806<procedure>(list? obj)</procedure><br>
2807
2808Returns #t if obj is a list, otherwise returns #f. By definition, all
2809lists have finite length and are terminated by the empty list.
2810
2811 (list? '(a b c))             ===>  #t
2812 (list? '())                  ===>  #t
2813 (list? '(a . b))             ===>  #f
2814 (let ((x (list 'a)))
2815   (set-cdr! x x)
2816   (list? x))                 ===>  #f
2817
2818<procedure>(make-list k [fill]}</procedure>
2819
2820Returns a newly allocated list of k elements. If a second argument is given, then each element is initialized to {{fill}}. Otherwise the initial contents of each element is unspecified.
2821
2822 (make-list 2 3)    ==>   (3 3)
2823
2824<procedure>(list obj ...)</procedure><br>
2825
2826Returns a newly allocated list of its arguments.
2827
2828 (list 'a (+ 3 4) 'c)                    ===>  (a 7 c)
2829 (list)                                  ===>  ()
2830
2831<procedure>(length list)</procedure><br>
2832
2833Returns the length of list.
2834
2835 (length '(a b c))                       ===>  3
2836 (length '(a (b) (c d e)))               ===>  3
2837 (length '())                            ===>  0
2838
2839<procedure>(append list ...)</procedure><br>
2840
2841Returns a list consisting of the elements of the first list followed by
2842the elements of the other lists.
2843
2844 (append '(x) '(y))                      ===>  (x y)
2845 (append '(a) '(b c d))                  ===>  (a b c d)
2846 (append '(a (b)) '((c)))                ===>  (a (b) (c))
2847
2848The resulting list is always newly allocated, except that it shares
2849structure with the last list argument. The last argument may actually
2850be any object; an improper list results if the last argument is not a
2851proper list.
2852
2853 (append '(a b) '(c . d))                ===>  (a b c . d)
2854 (append '() 'a)                         ===>  a
2855
2856<procedure>(reverse list)</procedure><br>
2857
2858Returns a newly allocated list consisting of the elements of list in
2859reverse order.
2860
2861 (reverse '(a b c))                      ===>  (c b a)
2862 (reverse '(a (b c) d (e (f))))
2863                 ===>  ((e (f)) d (b c) a)
2864
2865<procedure>(list-tail list k)</procedure><br>
2866
2867Returns the sublist of list obtained by omitting the first k elements.
2868It is an error if list has fewer than k elements. List-tail could be
2869defined by
2870
2871 (define list-tail
2872   (lambda (x k)
2873     (if (zero? k)
2874         x
2875         (list-tail (cdr x) (- k 1)))))
2876
2877<procedure>(list-ref list k)</procedure><br>
2878
2879Returns the kth element of list. (This is the same as the car of
2880(list-tail list k).) It is an error if list has fewer than k elements.
2881
2882 (list-ref '(a b c d) 2)                ===>  c
2883 (list-ref '(a b c d)
2884           (inexact->exact (round 1.8))) 
2885                 ===>  c
2886
2887<procedure>(list-set! list k obj)</procedure>
2888
2889It is an error if k is not a valid index of list.
2890
2891The {{list-set!}} procedure stores obj in element k of list.
2892
2893 (let ((ls (list 'one 'two 'five!)))
2894   (list-set! ls 2 'three)
2895   ls)      
2896 ==>  (one two three)
2897
2898 (list-set! '(0 1 2) 1 "oops")  
2899 ==> error  ; constant list
2900
2901<procedure>(memq obj list)</procedure><br>
2902<procedure>(memv obj list)</procedure><br>
2903<procedure>(member obj list [compare])</procedure><br>
2904
2905These procedures return the first sublist of list whose car is obj,
2906where the sublists of list are the non-empty lists returned by
2907{{(list-tail list k)}} for k less than the length of list. If obj does not
2908occur in list, then #f (not the empty list) is returned. {{memq}} uses {{eq?}}
2909to compare obj with the elements of list, while {{memv}} uses {{eqv?}} and
2910member {{compare}} if given, and {{equal?}} otherwise.
2911
2912 (memq 'a '(a b c))                      ===>  (a b c)
2913 (memq 'b '(a b c))                      ===>  (b c)
2914 (memq 'a '(b c d))                      ===>  #f
2915 (memq (list 'a) '(b (a) c))             ===>  #f
2916 (member (list 'a)
2917         '(b (a) c))                     ===>  ((a) c)
2918 (memq 101 '(100 101 102))               ===>  unspecified
2919 (memv 101 '(100 101 102))               ===>  (101 102)
2920
2921<procedure>(assq obj alist)</procedure><br>
2922<procedure>(assv obj alist)</procedure><br>
2923<procedure>(assoc obj alist [compare])</procedure><br>
2924
2925Alist (for "association list") must be a list of pairs. These
2926procedures find the first pair in alist whose car field is obj, and
2927returns that pair. If no pair in alist has obj as its car, then #f (not
2928the empty list) is returned. {{assq}} uses {{eq?}} to compare obj with the car
2929fields of the pairs in alist, while {{assv}} uses {{eqv?}} and {{assoc}} uses
2930{{compare}}, if given, otherwise {{equal?}}.
2931
2932 (define e '((a 1) (b 2) (c 3)))
2933 (assq 'a e)             ===>  (a 1)
2934 (assq 'b e)             ===>  (b 2)
2935 (assq 'd e)             ===>  #f
2936 (assq (list 'a) '(((a)) ((b)) ((c))))
2937                         ===>  #f
2938 (assoc (list 'a) '(((a)) ((b)) ((c))))   
2939                                    ===>  ((a))
2940 (assq 5 '((2 3) (5 7) (11 13)))    
2941                                    ===>  unspecified
2942 (assv 5 '((2 3) (5 7) (11 13)))    
2943                                    ===>  (5 7)
2944
2945Rationale:   Although they are ordinarily used as predicates, memq,
2946memv, member, assq, assv, and assoc do not have question marks in
2947their names because they return useful values rather than just #t
2948or #f.
2949
2950<procedure>(list-copy obj)</procedure>
2951
2952Returns a newly allocated copy of the given obj if it is a list. Only the pairs themselves are copied; the cars of the result are the same (in the sense of {{eqv?}}) as the cars of list. If obj is an improper list, so is the result, and the final cdrs are the same in
2953the sense of {{eqv?}}. An obj which is not a list is returned unchanged. It is an error if
2954obj is a circular list.
2955
2956 (define a '(1 8 2 8)) ; a may be immutable
2957 (define b (list-copy a))
2958 (set-car! b 3)        ; b is mutable
2959 b  ==> (3 8 2 8)
2960 a  ==> (1 8 2 8)
2961
2962==== Symbols
2963
2964Symbols are objects whose usefulness rests on the fact that two symbols
2965are identical (in the sense of eqv?) if and only if their names are
2966spelled the same way. This is exactly the property needed to represent
2967identifiers in programs, and so most implementations of Scheme use them
2968internally for that purpose. Symbols are useful for many other
2969applications; for instance, they may be used the way enumerated values
2970are used in Pascal.
2971
2972The rules for writing a symbol are exactly the same as the rules for
2973writing an identifier.
2974
2975It is guaranteed that any symbol that has been returned as part of a
2976literal expression, or read using the read procedure, and subsequently
2977written out using the write procedure, will read back in as the
2978identical symbol (in the sense of eqv?). The string->symbol procedure,
2979however, can create symbols for which this write/read invariance may
2980not hold because their names contain special characters or letters in
2981the non-standard case.
2982
2983Note:   Some implementations of Scheme have a feature known as
2984"slashification" in order to guarantee write/read invariance for
2985all symbols, but historically the most important use of this
2986feature has been to compensate for the lack of a string data type.
2987
2988Some implementations also have "uninterned symbols", which defeat
2989write/read invariance even in implementations with slashification,
2990and also generate exceptions to the rule that two symbols are the
2991same if and only if their names are spelled the same.
2992
2993<procedure>(symbol? obj)</procedure><br>
2994
2995Returns #t if obj is a symbol, otherwise returns #f.
2996
2997 (symbol? 'foo)                  ===>  #t
2998 (symbol? (car '(a b)))          ===>  #t
2999 (symbol? "bar")                 ===>  #f
3000 (symbol? 'nil)                  ===>  #t
3001 (symbol? '())                   ===>  #f
3002 (symbol? #f)                    ===>  #f
3003
3004<procedure>(symbol=? symbol[1] symbol[2] symbol[3] ...)</procedure>
3005
3006Returns #t if all the arguments all have the same names in the sense of {{string=?}}.
3007
3008Note: The definition above assumes that none of the arguments are uninterned symbols.
3009
3010<procedure>(symbol->string symbol)</procedure><br>
3011
3012Returns the name of symbol as a string. If the symbol was part of an
3013object returned as the value of a literal expression (see
3014"[[#literal-expressions|literal expressions]]") or by a call to the
3015read procedure, and its name contains alphabetic characters, then the
3016string returned will contain characters in the implementation's
3017preferred standard case -- some implementations will prefer upper
3018case, others lower case. If the symbol was returned by string->symbol,
3019the case of characters in the string returned will be the same as the
3020case in the string that was passed to string->symbol.  It is an error
3021to apply mutation procedures like string-set! to strings returned by
3022this procedure.
3023
3024The following examples assume that the implementation's standard case
3025is lower case:
3026
3027 (symbol->string 'flying-fish)     
3028                                           ===>  "flying-fish"
3029 (symbol->string 'Martin)                  ===>  "martin"
3030 (symbol->string
3031    (string->symbol "Malvina"))     
3032                                           ===>  "Malvina"
3033
3034<procedure>(string->symbol string)</procedure><br>
3035
3036Returns the symbol whose name is string. This procedure can create
3037symbols with names containing special characters or letters in the
3038non-standard case, but it is usually a bad idea to create such symbols
3039because in some implementations of Scheme they cannot be read as
3040themselves. See symbol->string.
3041
3042The following examples assume that the implementation's standard case
3043is lower case:
3044
3045 (eq? 'mISSISSIppi 'mississippi)  
3046                 ===>  #t
3047 (string->symbol "mISSISSIppi")  
3048                 ===>  the symbol with name "mISSISSIppi"
3049 (eq? 'bitBlt (string->symbol "bitBlt"))     
3050                 ===>  #f
3051 (eq? 'JollyWog
3052      (string->symbol
3053        (symbol->string 'JollyWog)))  
3054                 ===>  #t
3055 (string=? "K. Harper, M.D."
3056           (symbol->string
3057             (string->symbol "K. Harper, M.D.")))  
3058                 ===>  #t
3059
3060==== Characters
3061
3062Characters are objects that represent printed characters such as
3063letters and digits. Characters are written using the notation #\
3064<character> or #\<character name>. For example:
3065
3066Characters are written using the notation {{#\<character>}} or {{#\<character name>}}
3067or {{#\x<hex scalar value>}}.
3068
3069The following character names must be supported by all implementations with the
3070given values. Implementations may add other names provided they cannot be
3071interpreted as hex scalar values preceded by x.
3072
3073   #\alarm     ; U+0007
3074   #\backspace ; U+0008
3075   #\delete    ; U+007F
3076   #\escape    ; U+001B
3077   #\newline   ; the linefeed character, U+000A
3078   #\null      ; the null character, U+0000
3079   #\return    ; the return character, U+000D
3080   #\space     ; the preferred way to write a space
3081   #\tab       ; the tab character, U+0009
3082
3083Here are some additional examples:
3084
3085 #\a       ; lower case letter
3086 #\A       ; upper case letter
3087 #\(       ; left parenthesis
3088 #\        ; the space character
3089 #\space   ; the preferred way to write a space
3090 #\newline ; the newline character
3091
3092Case is significant in #\<character>, but not in #\<character name>. If
3093<character> in #\<character> is alphabetic, then the character
3094following <character> must be a delimiter character such as a space or
3095parenthesis. This rule resolves the ambiguous case where, for example,
3096the sequence of characters "#\space" could be taken to be either a
3097representation of the space character or a representation of the
3098character "#\s" followed by a representation of the symbol "pace."
3099
3100Characters written in the #\ notation are self-evaluating. That is,
3101they do not have to be quoted in programs. Some of the procedures that
3102operate on characters ignore the difference between upper case and
3103lower case. The procedures that ignore case have "-ci" (for "case
3104insensitive") embedded in their names.
3105
3106<procedure>(char? obj)</procedure><br>
3107
3108Returns #t if obj is a character, otherwise returns #f.
3109
3110<procedure>(char=? char[1] char[2] char[3] ...)</procedure><br>
3111<procedure>(char<? char[1] char[2] char[3] ...)</procedure><br>
3112<procedure>(char>? char[1] char[2] char[3] ...)</procedure><br>
3113<procedure>(char<=? char[1] char[2] char[3] ...)</procedure><br>
3114<procedure>(char>=? char[1] char[2] char[3] ...)</procedure><br>
3115
3116These procedures impose a total ordering on the set of characters. It
3117is guaranteed that under this ordering:
3118
3119*   The upper case characters are in order. For example, (char<? #\A #\
3120    B) returns #t.
3121*   The lower case characters are in order. For example, (char<? #\a #\
3122    b) returns #t.
3123*   The digits are in order. For example, (char<? #\0 #\9) returns #t.
3124*   Either all the digits precede all the upper case letters, or vice
3125    versa.
3126*   Either all the digits precede all the lower case letters, or vice
3127    versa.
3128
3129Some implementations may generalize these procedures to take more than
3130two arguments, as with the corresponding numerical predicates.
3131
3132<procedure>(char-ci=? char[1] char[2] char[3] ...)</procedure><br>
3133<procedure>(char-ci<? char[1] char[2] char[3] ...)</procedure><br>
3134<procedure>(char-ci>? char[1] char[2] char[3] ...)</procedure><br>
3135<procedure>(char-ci<=? char[1] char[2] char[3] ...)</procedure><br>
3136<procedure>(char-ci>=? char[1] char[2] char[3] ...)</procedure><br>
3137
3138These procedures are similar to char=? et cetera, but they treat upper
3139case and lower case letters as the same. For example, (char-ci=? #\A #\
3140a) returns #t. Some implementations may generalize these procedures to
3141take more than two arguments, as with the corresponding numerical
3142predicates.
3143
3144<procedure>(char-alphabetic? char)</procedure><br>
3145<procedure>(char-numeric? char)</procedure><br>
3146<procedure>(char-whitespace? char)</procedure><br>
3147<procedure>(char-upper-case? letter)</procedure><br>
3148<procedure>(char-lower-case? letter)</procedure><br>
3149
3150These procedures return #t if their arguments are alphabetic, numeric,
3151whitespace, upper case, or lower case characters, respectively,
3152otherwise they return #f. The following remarks, which are specific to
3153the ASCII character set, are intended only as a guide: The alphabetic
3154characters are the 52 upper and lower case letters. The numeric
3155characters are the ten decimal digits. The whitespace characters are
3156space, tab, line feed, form feed, and carriage return.
3157
3158<procedure>(char->integer char)</procedure><br>
3159<procedure>(integer->char n)</procedure><br>
3160
3161Given a character, char->integer returns an exact integer
3162representation of the character. Given an exact integer that is the
3163image of a character under char->integer, integer->char returns that
3164character. These procedures implement order-preserving isomorphisms
3165between the set of characters under the char<=? ordering and some
3166subset of the integers under the <= ordering. That is, if
3167
3168 (char<=? a b) ===> #t  and  (<= x y) ===> #t
3169
3170and x and y are in the domain of integer->char, then
3171
3172 (<= (char->integer a)
3173     (char->integer b))                  ===>  #t
3174 
3175 (char<=? (integer->char x)
3176          (integer->char y))             ===>  #t
3177
3178Note that {{integer->char}} does currently not detect
3179a negative argument and will quietly convert {{-1}} to
3180{{#x1ffff}} in CHICKEN.
3181
3182==== Strings
3183
3184Strings are sequences of characters. Strings are written as sequences of
3185characters enclosed within quotation marks ("). Within a string literal,
3186various escape sequences represent characters other than themselves. Escape
3187sequences always start with a backslash (\):
3188
3189* \a : alarm, U+0007
3190
3191* \b : backspace, U+0008
3192
3193* \t : character tabulation, U+0009
3194
3195* \n : linefeed, U+000A
3196
3197* \r : return, U+000D
3198
3199* \" : double quote, U+0022
3200
3201* \\ : backslash, U+005C
3202
3203* \| : vertical line, U+007C
3204
3205* \<intraline whitespace>*<line ending> <intraline whitespace>* : nothing
3206
3207* \x<hex scalar value>; : specified character (note the terminating
3208    semi-colon).
3209
3210The result is unspecified if any other character in a string occurs after a
3211backslash.
3212
3213Except for a line ending, any character outside of an escape sequence stands
3214for itself in the string literal. A line ending which is preceded by \
3215<intraline whitespace> expands to nothing (along with any trailing intraline
3216whitespace), and can be used to indent strings for improved legibility. Any
3217other line ending has the same effect as inserting a \n character into the
3218string.
3219
3220Examples:
3221
3222 "The word \"recursion\" has many meanings."
3223 "Another example:\ntwo lines of text"
3224 "Here's text \ 
3225    containing just one line"
3226 "\x03B1; is named GREEK SMALL LETTER ALPHA." 
3227
3228The length of a string is the
3229number of characters that it contains. This number is an exact, non-negative
3230integer that is fixed when the string is created. The valid indexes of a string
3231are the exact non-negative integers less than the length of the string. The
3232first character of a string has index 0, the second has index 1, and so on.
3233
3234<procedure>(string? obj)</procedure><br>
3235
3236Returns #t if obj is a string, otherwise returns #f.
3237
3238<procedure>(make-string k)</procedure><br>
3239<procedure>(make-string k char)</procedure><br>
3240
3241Make-string returns a newly allocated string of length k. If char is
3242given, then all elements of the string are initialized to char,
3243otherwise the contents of the string are unspecified.
3244
3245<procedure>(string char ...)</procedure><br>
3246
3247Returns a newly allocated string composed of the arguments.
3248
3249<procedure>(string-length string)</procedure><br>
3250
3251Returns the number of characters in the given string.
3252
3253<procedure>(string-ref string k)</procedure><br>
3254
3255k must be a valid index of string. String-ref returns character k of
3256string using zero-origin indexing.
3257
3258<procedure>(string-set! string k char)</procedure><br>
3259
3260k must be a valid index of string. String-set! stores char in element k
3261of string and returns an unspecified value.
3262
3263 (define (f) (make-string 3 #\*))
3264 (define (g) "***")
3265 (string-set! (f) 0 #\?)          ===>  unspecified
3266 (string-set! (g) 0 #\?)          ===>  error
3267 (string-set! (symbol->string 'immutable)
3268              0
3269              #\?)          ===>  error
3270
3271<procedure>(string=? string[1] string[2] string[3] ...)</procedure><br>
3272
3273Returns #t if the two strings are the same length and contain the same
3274characters in the same positions, otherwise returns #f. 
3275
3276<procedure>(string<? string[1] string[2] string[3] ...)</procedure><br>
3277<procedure>(string>? string[1] string[2] string[3] ...)</procedure><br>
3278<procedure>(string<=? string[1] string[2] string[3] ...)</procedure><br>
3279<procedure>(string>=? string[1] string[2] string[3] ...)</procedure><br>
3280
3281These procedures are the lexicographic extensions to strings of the
3282corresponding orderings on characters. For example, string<? is the
3283lexicographic ordering on strings induced by the ordering char<? on
3284characters. If two strings differ in length but are the same up to the
3285length of the shorter string, the shorter string is considered to be
3286lexicographically less than the longer string.
3287
3288<procedure>(substring string start [end])</procedure><br>
3289
3290String must be a string, and start and end must be exact integers
3291satisfying
3292
3293 0 <= start <= end <= (string-length string)
3294
3295Substring returns a newly allocated string formed from the characters
3296of string beginning with index start (inclusive) and ending with index
3297end (exclusive). The {{end}} argument is optional and defaults to the
3298length of the string, this is a non-standard extension in CHICKEN.
3299
3300<procedure>(string-append string ...)</procedure><br>
3301
3302Returns a newly allocated string whose characters form the
3303concatenation of the given strings.
3304
3305<procedure>(string->list string [start [end]])</procedure><br>
3306<procedure>(list->string list)</procedure><br>
3307
3308String->list returns a newly allocated list of the characters that make
3309up the given string between start and end. List->string returns a newly allocated string
3310formed from the characters in the list list, which must be a list of
3311characters. String->list and list->string are inverses so far as equal?
3312is concerned.
3313
3314<procedure>(string-copy string [start [end]])</procedure><br>
3315
3316Returns a newly allocated copy of the given string.
3317
3318<procedure>(string-copy! to at from [start [end]])</procedure>
3319
3320It is an error if at is less than zero or greater than the length of to. It is also an error if {{(- (string-length to) at)}} is less than {{(- end start)}}.
3321
3322Copies the characters of string from between start and end to string to, starting at
3323at. The order in which characters are copied is unspecified, except that if the
3324source and destination overlap, copying takes place as if the source is first
3325copied into a temporary string and then into the destination. This can be
3326achieved without allocating storage by making sure to copy in the correct
3327direction in such circumstances.
3328
3329 (define a "12345")
3330 (define b (string-copy "abcde"))
3331 (string-copy! b 1 a 0 2)
3332 b  ==> "a12de"
3333
3334<procedure>(string-fill! string char +#!optional start end)</procedure><br>
3335
3336Stores char in every element of the given string and returns an
3337unspecified value. The optional start and end arguments specify
3338the part of the string to be filled and default to the complete string.
3339
3340==== Vectors
3341
3342Vectors are heterogenous structures whose elements are indexed by
3343integers. A vector typically occupies less space than a list of the
3344same length, and the average time required to access a randomly chosen
3345element is typically less for the vector than for the list.
3346
3347The length of a vector is the number of elements that it contains. This
3348number is a non-negative integer that is fixed when the vector is
3349created. The valid indexes of a vector are the exact non-negative
3350integers less than the length of the vector. The first element in a
3351vector is indexed by zero, and the last element is indexed by one less
3352than the length of the vector.
3353
3354Vectors are written using the notation #(obj ...). For example, a
3355vector of length 3 containing the number zero in element 0, the list (2
33562 2 2) in element 1, and the string "Anna" in element 2 can be written
3357as following:
3358
3359 #(0 (2 2 2 2) "Anna")
3360
3361Vector constants are self-evaluating, so they do not need
3362to be quoted in programs.
3363
3364<procedure>(vector? obj)</procedure><br>
3365
3366Returns #t if obj is a vector, otherwise returns #f.
3367
3368<procedure>(make-vector k)</procedure><br>
3369<procedure>(make-vector k fill)</procedure><br>
3370
3371Returns a newly allocated vector of k elements. If a second argument is
3372given, then each element is initialized to fill. Otherwise the initial
3373contents of each element is unspecified.
3374
3375<procedure>(vector obj ...)</procedure><br>
3376
3377Returns a newly allocated vector whose elements contain the given
3378arguments. Analogous to list.
3379
3380 (vector 'a 'b 'c)                       ===>  #(a b c)
3381
3382<procedure>(vector-length vector)</procedure><br>
3383
3384Returns the number of elements in vector as an exact integer.
3385
3386<procedure>(vector-ref vector k)</procedure><br>
3387
3388k must be a valid index of vector. Vector-ref returns the contents of
3389element k of vector.
3390
3391 (vector-ref '#(1 1 2 3 5 8 13 21)
3392             5)  
3393                 ===>  8
3394 (vector-ref '#(1 1 2 3 5 8 13 21)
3395             (let ((i (round (* 2 (acos -1)))))
3396               (if (inexact? i)
3397                   (inexact->exact i)
3398                   i))) 
3399                 ===> 13
3400
3401<procedure>(vector-set! vector k obj)</procedure><br>
3402
3403k must be a valid index of vector. Vector-set! stores obj in element k
3404of vector. The value returned by vector-set! is unspecified.
3405
3406 (let ((vec (vector 0 '(2 2 2 2) "Anna")))
3407   (vector-set! vec 1 '("Sue" "Sue"))
3408   vec)      
3409                 ===>  #(0 ("Sue" "Sue") "Anna")
3410 
3411 (vector-set! '#(0 1 2) 1 "doe")  
3412                 ===>  error  ; constant vector
3413
3414<procedure>(vector->list vector [start [end]])</procedure><br>
3415<procedure>(list->vector list)</procedure><br>
3416
3417Vector->list returns a newly allocated list of the objects contained in
3418the elements of vector. List->vector returns a newly created vector
3419initialized to the elements of the list list.
3420
3421 (vector->list '#(dah dah didah))  
3422                 ===>  (dah dah didah)
3423 (list->vector '(dididit dah))   
3424                 ===>  #(dididit dah)
3425
3426<procedure>(vector-fill! vector fill)</procedure><br>
3427
3428Stores fill in every element of vector. The value returned by
3429vector-fill! is unspecified.
3430
3431<procedure>(vector->string vector [start [end]])</procedure><br>
3432<procedure(string->vector string [start [end]])</procedure>
3433
3434It is an error if any element of vector between start and end is not a character.
3435
3436The vector->string procedure returns a newly allocated string of the objects
3437contained in the elements of vector between start and end. The string->vector procedure returns a newly created vector initialized to
3438the elements of the string string between start and end.
3439
3440In both procedures, order is preserved.
3441
3442 (string->vector "ABC")   ==>   #(#\A #\B #\C)
3443 (vector->string #(#\1 #\2 #\3)  ==> "123"
3444
3445<procedure>(vector-copy vector [start [end]])</procedure>
3446
3447Returns a newly allocated copy of the elements of the given vector between
3448start and end. The elements of the new vector are the same (in the sense of eqv?) as the
3449elements of the old.
3450
3451 (define a #(1 8 2 8)) ; a may be immutable
3452 (define b (vector-copy a))
3453 (vector-set! b 0 3)   ; b is mutable
3454 b  ==> #(3 8 2 8)
3455 (define c (vector-copy b 1 3))
3456 c  ==> #(8 2)
3457
3458<procedure>(vector-copy! to at from [start [end]])</procedure>
3459
3460It is an error if at is less than zero or greater than the length of to. It is also an error if {{(- (vector-length to) at)}} is less than {{(- end start)}}.
3461
3462Copies the elements of vector from between start and end to vector to, starting at
3463at. The order in which elements are copied is unspecified, except that if the
3464source and destination overlap, copying takes place as if the source is first
3465copied into a temporary vector and then into the destination. This can be
3466achieved without allocating storage by making sure to copy in the correct
3467direction in such circumstances.
3468
3469 (define a (vector 1 2 3 4 5))
3470 (define b (vector 10 20 30 40 50))
3471 (vector-copy! b 1 a 0 2)
3472 b  ==> #(10 1 2 40 50)
3473
3474<procedure>(vector-append vector ....)</procedure>
3475
3476Returns a newly allocated vector whose elements are the concatenation of the
3477elements of the given vectors.
3478
3479 (vector-append #(a b c) #(d e f)) ==> #(a b c d e f)
3480
3481<procedure>(vector-fill! vector fill [start [end)]])</procedure>
3482
3483The vector-fill! procedure stores fill in the elements of vector between start and
3484end.
3485
3486 (define a (vector 1 2 3 4 5))
3487 (vector-fill! a 'smash 2 4)
3488 a ==>#(1 2 smash smash 5)
3489
3490====  Bytevectors
3491
3492Bytevectors represent blocks of binary data. They are fixed-length sequences of
3493bytes, where a byte is an exact integer in the range from 0 to 255 inclusive. A
3494bytevector is typically more space-efficient than a vector containing the same
3495values.
3496
3497See [[Module (chicken bytevector)|The (chicken bytevector) module]] for more
3498information. {{(scheme base)}} re-exports all R7RS-specific procedures from
3499that module.
3500
3501=== Control features
3502
3503This chapter describes various primitive procedures which control the
3504flow of program execution in special ways. The procedure? predicate is
3505also described here.
3506
3507<procedure>(procedure? obj)</procedure><br>
3508
3509Returns #t if obj is a procedure, otherwise returns #f.
3510
3511 (procedure? car)                    ===>  #t
3512 (procedure? 'car)                   ===>  #f
3513 (procedure? (lambda (x) (* x x)))   
3514                                     ===>  #t
3515 (procedure? '(lambda (x) (* x x)))  
3516                                     ===>  #f
3517 (call-with-current-continuation procedure?)
3518                                     ===>  #t
3519
3520<procedure>(apply proc arg[1] ... args)</procedure><br>
3521
3522Proc must be a procedure and args must be a list. Calls proc with the
3523elements of the list (append (list arg[1] ...) args) as the actual
3524arguments.
3525
3526 (apply + (list 3 4))                      ===>  7
3527 
3528 (define compose
3529   (lambda (f g)
3530     (lambda args
3531       (f (apply g args)))))
3532 
3533 ((compose sqrt *) 12 75)                      ===>  30
3534
3535<procedure>(map proc list[1] list[2] ...)</procedure><br>
3536
3537The lists must be lists, and proc must be a procedure taking as many
3538arguments as there are lists and returning a single value. Map applies
3539proc element-wise to the elements of the lists and returns a list of
3540the results, in order. The dynamic order in which proc is applied to
3541the elements of the lists is unspecified.
3542
3543Like in SRFI-1, this procedure allows the arguments to be of unequal
3544length; it terminates when the shortest list runs out.  This is a
3545CHICKEN extension to R7RS.
3546
3547 (map cadr '((a b) (d e) (g h)))   
3548                 ===>  (b e h)
3549 
3550 (map (lambda (n) (expt n n))
3551      '(1 2 3 4 5))                
3552                 ===>  (1 4 27 256 3125)
3553 
3554 (map + '(1 2 3) '(4 5 6))                 ===>  (5 7 9)
3555 
3556 (let ((count 0))
3557   (map (lambda (ignored)
3558          (set! count (+ count 1))
3559          count)
3560        '(a b)))                         ===>  (1 2) or (2 1)
3561
3562<procedure>(string-map proc string[1] string[2] ...)</procedure> 
3563
3564It is an error if proc does not accept as many arguments as there are strings and return a single character.
3565
3566The string-map procedure applies proc element-wise to the elements of the
3567strings and returns a string of the results, in order. If more than one
3568string is given and not all strings have the same length, string-map terminates
3569when the shortest string runs out. The dynamic order in which
3570proc is applied to the elements of the
3571strings is unspecified. If multiple returns occur from string-map, the values
3572returned by earlier returns are not mutated.
3573
3574 (string-map char-foldcase "AbdEgH") ==> "abdegh"
3575
3576 (string-map
3577  (lambda (c)
3578    (integer->char (+ 1 (char->integer c))))
3579  "HAL")                ==> "IBM"
3580
3581 (string-map
3582  (lambda (c k)
3583    ((if (eqv? k #\u) char-upcase char-downcase)
3584     c))
3585  "studlycaps xxx"
3586  "ululululul")         ==> "StUdLyCaPs"
3587
3588<procedure>(vector-map proc vector[1] vector[2] ...)</procedure>
3589
3590It is an error if proc does not accept as many arguments as there are vectors and return a single value.
3591
3592The vector-map procedure applies proc element-wise to the elements of the
3593vectors and returns a vector of the results, in order. If more than one
3594vector is given and not all vectors have the same length, vector-map terminates
3595when the shortest vector runs out. The dynamic order in which
3596proc is applied to the elements of the
3597vectors is unspecified. If multiple returns occur from vector-map, the values
3598returned by earlier returns are not mutated.
3599
3600 (vector-map cadr '#((a b) (d e) (g h)))   
3601 ==> #(b e h)
3602
3603 (vector-map (lambda (n) (expt n n))
3604             '#(1 2 3 4 5))                
3605 ==> #(1 4 27 256 3125)
3606
3607 (vector-map + '#(1 2 3) '#(4 5 6 7))       
3608 ==>  #(5 7 9)
3609
3610 (let ((count 0))
3611   (vector-map
3612    (lambda (ignored)
3613      (set! count (+ count 1))
3614      count)
3615    '#(a b)))                      ==>  #(1 2) or #(2 1)
3616
3617<procedure>(for-each proc list[1] list[2] ...)</procedure><br>
3618
3619The arguments to for-each are like the arguments to map, but for-each
3620calls proc for its side effects rather than for its values. Unlike map,
3621for-each is guaranteed to call proc on the elements of the lists in
3622order from the first element(s) to the last, and the value returned by
3623for-each is unspecified.
3624
3625 (let ((v (make-vector 5)))
3626   (for-each (lambda (i)
3627               (vector-set! v i (* i i)))
3628             '(0 1 2 3 4))
3629   v)                                        ===>  #(0 1 4 9 16)
3630
3631Like in SRFI-1, this procedure allows the arguments to be of unequal
3632length; it terminates when the shortest list runs out.  This is a
3633CHICKEN extension to R7RS.
3634
3635<procedure>(string-for-each proc string[1] string[2] ...)</procedure>
3636
3637It is an error if proc does not accept as many arguments as there are strings.
3638The arguments to string-for-each are like the arguments to string-map, but 
3639string-for-each calls
3640proc for its side effects rather than for its values. Unlike string-map, 
3641string-for-each is guaranteed to call
3642proc on the elements of the
3643strings in order from the first element(s) to the last, and the value returned
3644by string-for-each is unspecified. If more than one
3645string is given and not all strings have the same length, string-for-each
3646terminates when the shortest string runs out. It is an error for
3647proc to mutate any of the strings.
3648
3649 (let ((v '()))
3650   (string-for-each
3651    (lambda (c) (set! v (cons (char->integer c) v)))
3652    "abcde")
3653   v)                          ==>  (101 100 99 98 97)
3654
3655<procedure>(vector-for-each proc vector[1] vector[2] ...)</procedure>
3656
3657It is an error if proc does not accept as many arguments as there are vectors.
3658The arguments to vector-for-each are like the arguments to vector-map, but 
3659vector-for-each calls
3660proc for its side effects rather than for its values. Unlike vector-map, 
3661vector-for-each is guaranteed to call
3662proc on the elements of the
3663vectors in order from the first element(s) to the last, and the value returned
3664by vector-for-each is unspecified. If more than one
3665vector is given and not all vectors have the same length, vector-for-each
3666terminates when the shortest vector runs out. It is an error for
3667proc to mutate any of the vectors.
3668
3669 (let ((v (make-list 5)))
3670   (vector-for-each
3671    (lambda (i) (list-set! v i (* i i)))
3672    '#(0 1 2 3 4))
3673   v)                                 ==>  (0 1 4 9 16)
3674
3675<procedure>(call-with-current-continuation proc)</procedure><br>
3676<procedure>(call/cc proc)</procedure><br>
3677
3678Proc must be a procedure of one argument. The procedure
3679call-with-current-continuation packages up the current continuation
3680(see the rationale below) as an "escape procedure" and passes it as
3681an argument to proc. The escape procedure is a Scheme procedure that,
3682if it is later called, will abandon whatever continuation is in effect
3683at that later time and will instead use the continuation that was in
3684effect when the escape procedure was created. Calling the escape
3685procedure may cause the invocation of before and after thunks installed
3686using dynamic-wind.
3687
3688The escape procedure accepts the same number of arguments as the
3689continuation to the original call to call-with-current-continuation.
3690Except for continuations created by the call-with-values procedure, all
3691continuations take exactly one value. The effect of passing no value or
3692more than one value to continuations that were not created by
3693call-with-values is unspecified.
3694
3695The escape procedure that is passed to proc has unlimited extent just
3696like any other procedure in Scheme. It may be stored in variables or
3697data structures and may be called as many times as desired.
3698
3699The following examples show only the most common ways in which
3700call-with-current-continuation is used. If all real uses were as simple
3701as these examples, there would be no need for a procedure with the
3702power of call-with-current-continuation.
3703
3704 (call-with-current-continuation
3705   (lambda (exit)
3706     (for-each (lambda (x)
3707                 (if (negative? x)
3708                     (exit x)))
3709               '(54 0 37 -3 245 19))
3710     #t))                                ===>  -3
3711 
3712 (define list-length
3713   (lambda (obj)
3714     (call-with-current-continuation
3715       (lambda (return)
3716         (letrec ((r
3717                   (lambda (obj)
3718                     (cond ((null? obj) 0)
3719                           ((pair? obj)
3720                            (+ (r (cdr obj)) 1))
3721                           (else (return #f))))))
3722           (r obj))))))
3723 
3724 (list-length '(1 2 3 4))                    ===>  4
3725 
3726 (list-length '(a b . c))                    ===>  #f
3727
3728Rationale:
3729
3730A common use of call-with-current-continuation is for structured,
3731non-local exits from loops or procedure bodies, but in fact
3732call-with-current-continuation is extremely useful for implementing
3733a wide variety of advanced control structures.
3734
3735Whenever a Scheme expression is evaluated there is a continuation
3736wanting the result of the expression. The continuation represents
3737an entire (default) future for the computation. If the expression
3738is evaluated at top level, for example, then the continuation might
3739take the result, print it on the screen, prompt for the next input,
3740evaluate it, and so on forever. Most of the time the continuation
3741includes actions specified by user code, as in a continuation that
3742will take the result, multiply it by the value stored in a local
3743variable, add seven, and give the answer to the top level
3744continuation to be printed. Normally these ubiquitous continuations
3745are hidden behind the scenes and programmers do not think much
3746about them. On rare occasions, however, a programmer may need to
3747deal with continuations explicitly. Call-with-current-continuation
3748allows Scheme programmers to do that by creating a procedure that
3749acts just like the current continuation.
3750
3751Most programming languages incorporate one or more special-purpose
3752escape constructs with names like exit, return, or even goto. In
37531965, however, Peter Landin [16] invented a general purpose escape
3754operator called the J-operator. John Reynolds [24] described a
3755simpler but equally powerful construct in 1972. The catch special
3756form described by Sussman and Steele in the 1975 report on Scheme
3757is exactly the same as Reynolds's construct, though its name came
3758from a less general construct in MacLisp. Several Scheme
3759implementors noticed that the full power of the catch construct
3760could be provided by a procedure instead of by a special syntactic
3761construct, and the name call-with-current-continuation was coined
3762in 1982. This name is descriptive, but opinions differ on the
3763merits of such a long name, and some people use the name call/cc
3764instead.
3765
3766<procedure>(values obj ...)</procedure><br>
3767
3768Delivers all of its arguments to its continuation. Except for
3769continuations created by the call-with-values procedure, all
3770continuations take exactly one value. Values might be defined as
3771follows:
3772
3773 (define (values . things)
3774   (call-with-current-continuation 
3775     (lambda (cont) (apply cont things))))
3776
3777<procedure>(call-with-values producer consumer)</procedure><br>
3778
3779Calls its producer argument with no values and a continuation that,
3780when passed some values, calls the consumer procedure with those values
3781as arguments. The continuation for the call to consumer is the
3782continuation of the call to call-with-values.
3783
3784 (call-with-values (lambda () (values 4 5))
3785                   (lambda (a b) b))
3786                                                            ===>  5
3787 
3788 (call-with-values * -)                                     ===>  -1
3789
3790<procedure>(dynamic-wind before thunk after)</procedure><br>
3791
3792Calls thunk without arguments, returning the result(s) of this call.
3793Before and after are called, also without arguments, as required by the
3794following rules (note that in the absence of calls to continuations
3795captured using call-with-current-continuation the three arguments are
3796called once each, in order). Before is called whenever execution enters
3797the dynamic extent of the call to thunk and after is called whenever it
3798exits that dynamic extent. The dynamic extent of a procedure call is
3799the period between when the call is initiated and when it returns. In
3800Scheme, because of call-with-current-continuation, the dynamic extent
3801of a call may not be a single, connected time period. It is defined as
3802follows:
3803
3804*   The dynamic extent is entered when execution of the body of the
3805    called procedure begins.
3806
3807*   The dynamic extent is also entered when execution is not within the
3808    dynamic extent and a continuation is invoked that was captured
3809    (using call-with-current-continuation) during the dynamic extent.
3810
3811*   It is exited when the called procedure returns.
3812
3813*   It is also exited when execution is within the dynamic extent and a
3814    continuation is invoked that was captured while not within the
3815    dynamic extent.
3816
3817If a second call to dynamic-wind occurs within the dynamic extent of
3818the call to thunk and then a continuation is invoked in such a way that
3819the afters from these two invocations of dynamic-wind are both to be
3820called, then the after associated with the second (inner) call to
3821dynamic-wind is called first.
3822
3823If a second call to dynamic-wind occurs within the dynamic extent of
3824the call to thunk and then a continuation is invoked in such a way that
3825the befores from these two invocations of dynamic-wind are both to be
3826called, then the before associated with the first (outer) call to
3827dynamic-wind is called first.
3828
3829If invoking a continuation requires calling the before from one call to
3830dynamic-wind and the after from another, then the after is called
3831first.
3832
3833The effect of using a captured continuation to enter or exit the
3834dynamic extent of a call to before or after is undefined.  However,
3835in CHICKEN it is safe to do this, and they will execute in the outer
3836dynamic context of the {{dynamic-wind}} form.
3837
3838 (let ((path '())
3839       (c #f))
3840   (let ((add (lambda (s)
3841                (set! path (cons s path)))))
3842     (dynamic-wind
3843       (lambda () (add 'connect))
3844       (lambda ()
3845         (add (call-with-current-continuation
3846                (lambda (c0)
3847                  (set! c c0)
3848                  'talk1))))
3849       (lambda () (add 'disconnect)))
3850     (if (< (length path) 4)
3851         (c 'talk2)
3852         (reverse path))))
3853 
3854                 ===> (connect talk1 disconnect
3855                       connect talk2 disconnect)
3856
3857=== Exceptions
3858
3859This section describes Scheme’s exception-handling and exception-raising
3860procedures. 
3861
3862Exception handlers are one-argument procedures that determine the action the
3863program takes when an exceptional situation is signaled. The system implicitly
3864maintains a current exception handler in the dynamic environment.
3865
3866The program raises an exception by invoking the current exception handler,
3867passing it an object encapsulating information about the exception. Any
3868procedure accepting one argument can serve as an exception handler and any
3869object can be used to represent an exception.
3870
3871<procedure>(with-exception-handler handler thunk)</procedure>
3872
3873It is an error if handler does not accept one argument. It is also an error if
3874thunk does not accept zero arguments.
3875The with-exception-handler procedure returns the results of invoking
3876thunk.
3877Handler is installed as the current exception handler in the dynamic
3878environment used for the invocation of
3879thunk.
3880
3881 (call-with-current-continuation
3882  (lambda (k)
3883   (with-exception-handler
3884    (lambda (x)
3885     (display "condition: ")
3886     (write x)
3887     (newline)
3888     (k 'exception))
3889    (lambda ()
3890     (+ 1 (raise 'an-error))))))
3891          ==> exception and prints "condition: an-error"
3892
3893 (with-exception-handler
3894  (lambda (x)
3895   (display "something went wrong\n"))
3896  (lambda ()
3897   (+ 1 (raise 'an-error))))
3898
3899prints  "something went wrong" 
3900After printing, the second example then raises another exception.
3901
3902<procedure>(raise obj)</procedure>
3903
3904Raises an exception by invoking the current exception handler on
3905obj. The handler is called with the same dynamic environment as that of the
3906call to raise, except that the current exception handler is the one that was in
3907place when the handler being called was installed. If the handler returns, a
3908secondary exception is raised in the same dynamic environment as the handler.
3909The relationship between
3910obj and the object raised by the secondary exception is unspecified.
3911
3912<procedure>(raise-continuable obj)</procedure>
3913
3914Raises an exception by invoking the current exception handler on
3915obj. The handler is called with the same dynamic environment as the call to 
3916raise-continuable, except that: (1) the current exception handler is the one
3917that was in place when the handler being called was installed, and (2) if the
3918handler being called returns, then it will again become the current exception
3919handler. If the handler returns, the values it returns become the values
3920returned by the call to raise-continuable.
3921
3922 (with-exception-handler
3923   (lambda (con)
3924     (cond
3925       ((string? con)
3926        (display con))
3927       (else
3928        (display "a warning has been issued")))
3929     42)
3930   (lambda ()
3931     (+ (raise-continuable "should be a number")
3932        23)))
3933     prints: "should be a number"
3934     ==> 65
3935
3936<procedure>(error [location] message obj ...)</procedure>
3937
3938Message should be a string.
3939Raises an exception as if by calling raise on a newly allocated
3940implementation-defined object which encapsulates the information provided by
3941message, as well as any
3942objs, known as the irritants. The procedure error-object? must return #t on
3943such objects.
3944
3945 (define (null-list? l)
3946   (cond ((pair? l) #f)
3947         ((null? l) #t)
3948         (else
3949           (error
3950             "null-list?: argument out of domain"
3951             l))))
3952
3953If location is given and a symbol, it indicates the name of the procedure where
3954the error occurred.
3955
3956<procedure>(error-object? obj)</procedure>
3957
3958Returns #t if
3959obj is an object created by error or one of an implementation-defined set of
3960objects. Otherwise, it returns #f. The objects used to signal errors, including
3961those which satisfy the predicates file-error? and read-error?, may or may not
3962satisfy error-object?.
3963
3964<procedure>(error-object-message error-object)</procedure>
3965
3966Returns the message encapsulated by
3967error-object.
3968
3969<procedure>(error-object-irritants error-object)</procedure>
3970
3971Returns a list of the irritants encapsulated by
3972error-object.
3973
3974<procedure>(read-error? obj)</procedure><br>
3975<procedure>(file-error? obj)</procedure>
3976
3977Error type predicates. Returns #t if
3978obj is an object raised by the read procedure or by the inability to open an
3979input or output port on a file, respectively. Otherwise, it returns #f.
3980
3981=== Eval
3982
3983<procedure>(eval expression [environment-specifier])</procedure><br>
3984
3985Evaluates expression in the specified environment and returns its
3986value. Expression must be a valid Scheme expression represented as
3987data, and environment-specifier must be a value returned by one of the
3988three procedures described below. Implementations may extend eval to
3989allow non-expression programs (definitions) as the first argument and
3990to allow other values as environments, with the restriction that eval
3991is not allowed to create new bindings in the environments associated
3992with null-environment or scheme-report-environment.
3993
3994 (eval '(* 7 3) (scheme-report-environment 5))
3995                                                            ===>  21
3996 
3997 (let ((f (eval '(lambda (f x) (f x x))
3998                (null-environment 5))))
3999   (f + 10))
4000                                                            ===>  20
4001
4002The {{environment-specifier}} is optional, and if not provided it
4003defaults to the value of {{(interaction-environment)}}.  This is a
4004CHICKEN extension to R7RS, which, though strictly nonportable, is very
4005common among Scheme implementations.
4006
4007=== Input and output
4008
4009==== Ports
4010
4011Ports represent input and output devices. To Scheme, an input port is a Scheme
4012object that can deliver data upon command, while an output port is a Scheme
4013object that can accept data.
4014
4015Different port types operate on different data. Scheme implementations are
4016required to support textual ports and binary ports, but may also provide other
4017port types.
4018
4019A textual port supports reading or writing of individual characters from or to
4020a backing store containing characters using read-char and write-char below, and
4021it supports operations defined in terms of characters, such as read and write.
4022
4023A binary port supports reading or writing of individual bytes from or to a
4024backing store containing bytes using read-u8 and write-u8 below, as well as
4025operations defined in terms of bytes. Whether the textual and binary port types
4026are disjoint is implementation-dependent.
4027
4028Ports can be used to access files, devices, and similar things on the host
4029system on which the Scheme program is running.
4030
4031<procedure>(call-with-port port proc)</procedure>
4032
4033It is an error if
4034proc does not accept one argument.
4035The call-with-port procedure calls
4036proc with
4037port as an argument. If
4038proc returns, then the port is closed automatically and the values yielded by
4039the
4040proc are returned. If
4041
4042proc does not return, then the port must not be closed automatically unless it
4043is possible to prove that the port will never again be used for a read or write
4044operation.
4045
4046    Rationale: Because Scheme’s escape procedures have unlimited extent, it is
4047    possible to escape from the current continuation but later to resume it. If
4048    implementations were permitted to close the port on any escape from the
4049    current continuation, then it would be impossible to write portable code
4050    using both call-with-current-continuation and call-with-port.
4051
4052Ports represent input and output devices. To Scheme, an input port is a
4053Scheme object that can deliver characters upon command, while an output
4054port is a Scheme object that can accept characters.
4055
4056<procedure>(input-port? obj)</procedure><br>
4057<procedure>(output-port? obj)</procedure><br>
4058<procedure>(textual-port? obj)</procedure><br>
4059<procedure>(binary-port? obj)</procedure><br>
4060<procedure>(port? obj)</procedure>
4061
4062These procedures return #t if
4063obj is an input port, output port, textual port, binary port, or any kind of
4064port, respectively. Otherwise they return #f.
4065
4066<procedure>(input-port-open? port)</procedure><br>
4067<procedure>(output-port-open? port)</procedure>
4068
4069Returns #t if
4070port is still open and capable of performing input or output, respectively, and
4071#f otherwise.
4072
4073<procedure>(current-input-port [port])</procedure><br>
4074<procedure>(current-output-port [port])</procedure><br>
4075<procedure>(current-error-port [port])</procedure><br>
4076
4077Returns the current default input, output or error port.
4078
4079If the optional {{port}} argument is passed, the current input or
4080output port is changed to the provided port.  It can also be used with
4081{{parameterize}} to temporarily bind the port to another value.  This
4082is a CHICKEN extension to the R7RS standard.
4083
4084Note that the default output port is not buffered. Use
4085[[Module (chicken port)#set-buffering-mode!|{{set-buffering-mode!}}]]
4086if you need a different behavior.
4087
4088<procedure>(open-input-file filename [mode ...])</procedure><br>
4089<procedure>(open-binary-input-file filename [mode ...])</procedure>
4090
4091Takes a string naming an existing file and returns an input port
4092capable of delivering textual or binary data from the file. If the file cannot be
4093opened, an error is signalled.
4094
4095Additional {{mode}} arguments can be passed in, which should be any of
4096the keywords {{#:text}} or {{#:binary}}.  These indicate the mode in
4097which to open the file (this has an effect on non-UNIX platforms
4098only).  The extra {{mode}} arguments are CHICKEN extensions to the
4099R7RS standard.
4100
4101<procedure>(close-port port)</procedure><br>
4102<procedure>(close-input-port port)</procedure><br>
4103<procedure>(close-output-port port)</procedure><br>
4104
4105Closes the resource associated with
4106port, rendering the
4107port incapable of delivering or accepting data. It is an error to apply the
4108last two procedures to a port which is not an input or output port,
4109respectively. Scheme implementations may provide ports which are simultaneously
4110input and output ports, such as sockets; the close-input-port and 
4111close-output-port procedures can then be used to close the input and output
4112sides of the port independently.
4113
4114These routines have no effect if the port has already been closed.
4115
4116<procedure>(open-input-string string)</procedure>
4117
4118Takes a string and returns a textual input port that delivers characters from
4119the string. If the string is modified, the effect is unspecified.
4120
4121<procedure>(open-output-string)</procedure>
4122
4123Returns a textual output port that will accumulate characters for retrieval by 
4124get-output-string.
4125
4126<procedure>(get-output-string port)</procedure>
4127
4128It is an error if
4129port was not created with open-output-string.
4130Returns a string consisting of the characters that have been output to the port
4131so far in the order they were output. If the result string is modified, the
4132effect is unspecified.
4133
4134 (parameterize
4135     ((current-output-port
4136       (open-output-string)))
4137     (display "piece")
4138     (display " by piece ")
4139     (display "by piece.")
4140     (newline)
4141     (get-output-string (current-output-port)))
4142   ==> "piece by piece by piece.\n"
4143
4144<procedure>(open-input-bytevector bytevector)</procedure>
4145
4146Takes a bytevector and returns a binary input port that delivers bytes from the
4147bytevector.
4148
4149<procedure>(open-output-bytevector)</procedure>
4150
4151Returns a binary output port that will accumulate bytes for retrieval by 
4152get-output-bytevector.
4153
4154<procedure>(get-output-bytevector port)</procedure>
4155
4156It is an error if
4157port was not created with open-output-bytevector.
4158Returns a bytevector consisting of the bytes that have been output to the port
4159so far in the order they were output.
4160
4161==== Input
4162
4163If port is omitted from any input procedure, it defaults to the value returned by 
4164(current-input-port). It is an error to attempt an input operation on a closed
4165port.
4166
4167<procedure>(read-char [port])</procedure><br>
4168
4169Returns the next character available from the input port, updating the
4170port to point to the following character. If no more characters are
4171available, an end of file object is returned. Port may be omitted, in
4172which case it defaults to the value returned by current-input-port.
4173
4174<procedure>(peek-char [port])</procedure><br>
4175
4176Returns the next character available from the input port, without
4177updating the port to point to the following character. If no more
4178characters are available, an end of file object is returned. Port may
4179be omitted, in which case it defaults to the value returned by
4180current-input-port.
4181
4182Note:   The value returned by a call to peek-char is the same as
4183the value that would have been returned by a call to read-char with
4184the same port. The only difference is that the very next call to
4185read-char or peek-char on that port will return the value returned
4186by the preceding call to peek-char. In particular, a call to
4187peek-char on an interactive port will hang waiting for input
4188whenever a call to read-char would have hung.
4189
4190<procedure>(read-line [port])</procedure>
4191
4192Returns the next line of text available from the textual input
4193port, updating the
4194port to point to the following character. If an end of line is read, a string
4195containing all of the text up to (but not including) the end of line is
4196returned, and the port is updated to point just past the end of line. If an end
4197of file is encountered before any end of line is read, but some characters have
4198been read, a string containing those characters is returned. If an end of file
4199is encountered before any characters are read, an end-of-file object is
4200returned. For the purpose of this procedure, an end of line consists of either
4201a linefeed character, a carriage return character, or a sequence of a carriage
4202return character followed by a linefeed character. Implementations may also
4203recognize other end of line characters or sequences.
4204
4205<procedure>(eof-object? obj)</procedure><br>
4206
4207Returns #t if obj is an end of file object, otherwise returns #f. The
4208precise set of end of file objects will vary among implementations, but
4209in any case no end of file object will ever be an object that can be
4210read in using read.
4211
4212<procedure>(eof-object)</procedure>
4213
4214Returns an end-of-file object, not necessarily unique.
4215
4216<procedure>(char-ready? [port])</procedure><br>
4217
4218Returns #t if a character is ready on the input port and returns #f
4219otherwise. If char-ready returns #t then the next read-char operation
4220on the given port is guaranteed not to hang. If the port is at end of
4221file then char-ready? returns #t. Port may be omitted, in which case it
4222defaults to the value returned by current-input-port.
4223
4224Rationale:   Char-ready? exists to make it possible for a program
4225to accept characters from interactive ports without getting stuck
4226waiting for input. Any input editors associated with such ports
4227must ensure that characters whose existence has been asserted by
4228char-ready? cannot be rubbed out. If char-ready? were to return #f
4229at end of file, a port at end of file would be indistinguishable
4230from an interactive port that has no ready characters.
4231
4232<procedure>(read-string k [port])</procedure>
4233
4234See [[Module (chicken io)|(chicken io) module]] for more information.
4235
4236<procedure>(read-u8 [port])</procedure>
4237
4238Returns the next byte available from the binary input
4239port, updating the
4240port to point to the following byte. If no more bytes are available, an
4241end-of-file object is returned.
4242
4243<procedure>(peek-u8 [port])</procedure>
4244
4245Returns the next byte available from the binary input
4246port, but without updating the
4247port to point to the following byte. If no more bytes are available, an
4248end-of-file object is returned.
4249
4250<procedure>(u8-ready? [port])</procedure>
4251
4252Returns #t if a byte is ready on the binary input
4253port and returns #f otherwise. If u8-ready? returns #t then the next read-u8
4254operation on the given
4255port is guaranteed not to hang. If the
4256port is at end of file then u8-ready?​ ​returns #t.
4257
4258<procedure>(read-bytevector k [port])</procedure><br>
4259<procedure>(read-bytevector! bytevector [port [start [end]]])</procedure>
4260
4261See [[Module (chicken io)|(chicken io) module]] for more information.
4262
4263==== Output
4264
4265If port is omitted from any output procedure, it defaults to the value returned by
4266(current-output-port). It is an error to attempt an output operation on a
4267closed port.
4268
4269<procedure>(newline)</procedure><br>
4270<procedure>(newline port)</procedure><br>
4271
4272Writes an end of line to port. Exactly how this is done differs from
4273one operating system to another. Returns an unspecified value. The port
4274argument may be omitted, in which case it defaults to the value
4275returned by current-output-port.
4276
4277<procedure>(write-char char)</procedure><br>
4278<procedure>(write-char char port)</procedure><br>
4279
4280Writes the character char (not an external representation of the
4281character) to the given port and returns an unspecified value. The port
4282argument may be omitted, in which case it defaults to the value
4283returned by current-output-port.
4284
4285<procedure>(write-string string [port [start [end]]])</procedurew>
4286
4287Writes the characters of
4288string from
4289start to
4290end in left-to-right order to the textual output
4291port.
4292
4293<procedure>(write-u8 byte [port])</procedure>
4294
4295Writes the
4296byte to the given binary output
4297port and returns an unspecified value.
4298
4299<procedure>(write-bytevector bytevector [port [start [end]]])</procedure>
4300
4301See [[Module (chicken bytevector)|The (chicken bytevector) module]] for more
4302information. 
4303
4304<procedure>(flush-output-port [port])</procedure>
4305
4306Flushes any buffered output from the buffer of output-port to the underlying
4307file or device and returns an unspecified value.
4308
4309==== System interface
4310
4311Questions of system interface generally fall outside of the domain of
4312this report. However, the following operations are important enough to
4313deserve description here.
4314
4315<procedure>(features)</procedure>
4316
4317Returns a list of the feature identifiers which cond-expand treats as true. It
4318is an error to modify this list. Here is an example of what features might
4319return:
4320
4321 (features)  ==>
4322   (r7rs ratios exact-complex full-unicode
4323    gnu-linux little-endian 
4324    fantastic-scheme
4325    fantastic-scheme-1.0
4326    space-ship-control-system)
4327
4328---
4329Previous: [[Module scheme]]
4330
4331Next: [[Module (scheme case-lambda)]]