This is sizzle-ref.info, produced by makeinfo version 4.0 from
sizzle-ref.texi.

INFO-DIR-SECTION Sizzle Scheme Interpreter
START-INFO-DIR-ENTRY
* sizzle-ref: (sizzle-ref).     Sizzle reference manual.
END-INFO-DIR-ENTRY

   This file documents the Sizzle Scheme interpreter.

   Copyright (C) 1999, 2000 Martin Grabmueller

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.


File: sizzle-ref.info,  Node: Predefined Variables,  Next: Builtin Procedures,  Prev: Programming Scheme,  Up: Top

Predefined Variables
********************

   In the Sizzle core, some variables are defined which can be used from
within Sizzle scripts to control and modify Sizzle's behaviour.

   Variables labelled as Library variables are defined in the startup
file `init.scm' and thus are only present if the embedding application
has loaded that file on startup.

 - Variable: %load-path
     A list of directory names to search when loading Scheme source
     files.  Initially, only the directories where the Sizzle startup
     file is located and the directory for site-specific Scheme files
     is in the list.  The user can add more directories if needed.
     Currently, only the `load' library procedure from the system init
     file uses this variable.

 - Variable: %sizzle-version%
     This is a string containing version information of the running
     interpreter. It has the format `major.minor.patchlevel', and looks
     like this: `0.0.30'.

 - Library variable: %sizzle-major-version%
 - Library variable: %sizzle-minor-version%
 - Library variable: %sizzle-patchlevel%
     These variables hold the components of %SIZZLE-VERSION%, split up
     at the dots and converted to integers.

     These variables are not defined when the option `-n,
     --no-system-init-file' is passed to the interpreter, or if the
     system startup file is not found.

 - Variable: %write-history-file%
     Boolean variable which controls whether the readline history will
     be written to the file `~/.sizzle_history' when the interpreter
     terminates.  By default this is false.  A good place to set this
     variable is in your `~/.sizzle' personal initialization file.

     (Only available if the optional module `(readline readline)' was
     used).

 - Variable: gc-message
     This is a boolean variable.  If set to `#t', a message will be
     printed whenever the garbage collection is invoked or the cell heap
     grows.

 - Variable: %max-evaluate-stack%
     Integer variable which holds the maximum evaluation stack size
     which is allowed. When the current stack size exceeds this value,
     an error is signalled. This variable can be set by user code to
     allow deeper recursion, but be careful: when setting this variable
     to very high values and performing heavy recursive evaluations
     Sizzle sometimes dumps core, because it runs out of stack space.

 - Variable: %print-read%
     Boolean variable which controls whether expressions read in are
     printed before evaluating. Mostly for debugging purposes.

 - Variable: %print-result%
     Boolean variable which controls whether expressions are printed
     after evaluation even when loading script files. Mostly for
     debugging purposes.

 - Variable: %print-memoized%
     Boolean variable which controls the way memoized expressions are
     printed.  If true, memoized global and local variables are printed
     in a more verbose way; but then the output of `(backtrace)' is
     much less readable, so this is false by default.

 - Variable: %print-func-bodies%
     Boolean variable which controls whether user-define procedures are
     printed with their procedure bodies or not.  If set to `#f', only
     the procedure name is printed and the formal parameter list.

 - Variable: %save-backtrace%
     Boolean variable which controls whether a procedure call history
     is kept which can be displayed for debugging purposes when errors
     occur. If you set this to `#t', the interpreter will consume a lot
     of memory if your program is heavily recursive.

 - Variable: %print-backtrace%
     Boolean variable which controls whether procedure call backtraces
     are printed immediately after an error or an exception occurs.  If
     set to `#t', backtraces are only printed when the primitive
     `backtrace' is called.

 - Variable: %print-backtrace-limit%
     Integer variable which controls how many lines of backtrace are
     printed when an error occurs.  You have to set both
     `eval-save-backtrace' and `eval-print-backtrace' to `#t' if you
     want backtraces.

 - Variable: %eval-time-taken%
     This integer variable holds the time in ticks which the last
     top-level evaluation took.


File: sizzle-ref.info,  Node: Builtin Procedures,  Next: Sizzle vs R5RS,  Prev: Predefined Variables,  Up: Top

Builtin Procedures
******************

   Sizzle comes with a large number of builtin functions and special
forms. The difference between these two is that the arguments to a
function are evaluated before the function is called, the arguments to a
special form are only evaluated when needed. This makes a difference for
forms like `set!', because the first argument (a symbol) needs not be
to be quoted like it would have to if `set!'  was a function. Also it
is necessary for forms which evaluate their arguments only when a
certain condition holds. `if', for example, only evaluates its third
argument if the first evaluates to the value `#t'.

   The provided procedures are grouped into two classes: primitive and
library.  Procedures which are labelled library are only available if
the library files, which are installed together with Sizzle, are loaded
on initialization.  This will be the case if you installed Sizzle
properly.

* Menu:

* Equality tests::              Testing values for equality
* Numerical operations::        Functions for dealing with numeric values
* Boolean operations::          Functions for dealing with boolean values
* Pair and list operations::    Functions for dealing with boolean values
* Hash table operations::       Functions for manipulating hash tables
* Symbol operations::           Functions for dealing with symbols
* Character operations::        Functions for dealing with characters
* String operations::           Functions for dealing with strings
* Vector operations::           Functions for dealing with vectors
* Homogenous Vector Operations::  Functions for dealing with uniform vectors
* Control flow operations::     Functions for controlling control flow
* Eval function::               Evaluating dynamically created expressions
* Debugging Support::           Support for chasing bugs
* Input and output::            Functions for interacting with the world
* Regular expression functions::  Functions for matching text
* System interface functions::  Functions for interfacing with the system
* Network Procedures::          Network programming support
* Module System::               Module definition and handling
* Dynamic Loading::             Dynamic loading of shared libraries.
* Macro functions::             Macro definition and expanding functions
* Runtime system::              Interfacing the Sizzle runtime system
* Self-Documentation::          Help and documentation utilities
* Box Operations::              Operations on box objects.
* Pointer Operations::          Operations on pointer objects
* Misc functions::              Unsorted functions
* Syntactic Forms::             if, lambda and friends


File: sizzle-ref.info,  Node: Equality tests,  Next: Numerical operations,  Prev: Builtin Procedures,  Up: Builtin Procedures

Equality tests
==============

   The following three procedures provide tests for three different
degrees of equality.  They are always available in the interpreter.

 - Primitive procedure: eq? obj1 obj2
     Returns `#t' if OBJ1 and OBJ2 are the same values, that means if
     both are stored at the same location in memory.  Symbols with the
     same textual representation pass this test, strings don't.  For
     numbers, the result is not predictable, `(eq? 1 1)' can return
     `#t', but not necessarily. Use `eqv?' or `=' to test numbers for
     equality. Strings can only compared using the predicate `equal?'
     or one of the string comparison predicates.

 - Primitive procedure: eqv? obj1 obj2
     This is the same as `eq?' but differs as far as numbers are
     concerned. That means that `(eqv? 1.0 1.0)' return `#t' in any
     case.

 - Primitive procedure: equal? obj1 obj2
     Returns `#t' if the structure of OBJ1 and OBJ2 is the same. You
     can use `equal?' to test lists, vectors and strings for equality,
     these data structures are tested recursively.  If you want to
     compare strings, use this procedure, or use the procedure
     `string=?'.


File: sizzle-ref.info,  Node: Numerical operations,  Next: Boolean operations,  Prev: Equality tests,  Up: Builtin Procedures

Numerical operations
====================

   The numerical operations documented in this section are available on
all platforms without needing additional modules.

 - Primitive procedure: number? obj
     Returns `#t' if OBJ is a number, `#f' otherwise.

 - Primitive procedure: complex? obj
     Returns `#t' if OBJ is a complex number, `#f' otherwise.

 - Primitive procedure: real? obj
     Returns `#t' if OBJ is a inexact number in floating point
     representation, `#f' otherwise.

 - Primitive procedure: rational? obj
     Returns `#t' if OBJ is a rational number, `#f' otherwise.

 - Primitive procedure: integer? obj
     Returns `#t' if OBJ is an exact integer number, `#f' otherwise.

 - Primitive procedure: long? obj
     Returns `#t' if OBJ is an exact long integer number (a
     non-immediate integer, not a bignum), `#f' otherwise.

 - Primitive procedure: exact? obj
     Returns `#t' if OBJ is an exact number, `#f' otherwise.

 - Primitive procedure: inexact? obj
     Returns `#t' if OBJ is an inexact number, `#f' otherwise.

 - Primitive procedure: = z1 z2 z3 ...
     Returns `#t' if all arguments are numerically equal, `#f'
     otherwise.

 - Primitive procedure: != z1 z2 z3 ...
     Returns `#t' if all arguments after the first are not numerically
     equal to the first argument, `#f' otherwise.

 - Primitive procedure: < z1 z2 z3 ...
     Returns `#t' if all arguments are strictly ordered in increasing
     order.

 - Primitive procedure: <= z1 z2 z3 ...
     Returns `#t' if all arguments are ordered in increasing order.

 - Primitive procedure: > z1 z2 z3 ...
     Returns `#t' if all arguments are strictly ordered in decreasing
     order.

 - Primitive procedure: >= z1 z2 z3 ...
     Returns `#t' if all arguments are ordered in decreasing order.

 - Primitive procedure: zero? obj
     Returns `#t' if OBJ is equal to zero, `#f' otherwise.

 - Primitive procedure: positive? obj
     Returns `#t' if OBJ is greater than zero, `#f' otherwise.

 - Primitive procedure: negative? obj
     Returns `#t' if OBJ is less than zero, `#f' otherwise.

 - Primitive procedure: odd? obj
     Returns `#t' if OBJ is an odd number, `#f' otherwise.

 - Primitive procedure: even? obj
     Returns `#t' if OBJ is an even number, `#f' otherwise.

 - Primitive procedure: max x1 x2 ...
     Returns the maximum of its arguments.

 - Primitive procedure: min x1 x2 ...
     Returns the minimum of its arguments.

 - Primitive procedure: + z1 ...
     Adds all numbers in the argument list and returns the sum.  If
     called without parameters, 0 is returned.

 - Primitive procedure: * z1 ...
     Multiplies all argument values and returns the product. Returns 1
     if called without parameters.

 - Primitive procedure: - z1 ...
     Takes the first argument and subtracts all remaining argument
     values one after the other. At least one parameter is required, if
     called with exactly one parameter, the negated value of the
     parameter is returned.

 - Primitive procedure: / z1 ...
     Divides the first argument by all remaining arguments in turn. If
     called with one parameter, the reciprocal of the argument is
     returned. Should any of the remaining arguments be zero, a
     division-by-zero error is signalled.

 - Primitive procedure: abs x
     Returns the absolute value of its argument.

 - Primitive procedure: magnitude z
     Returns the magnitude for X.  This is the same as `abs', since
     Sizzle does not support complex numbers.

 - Primitive procedure: angle z
     Returns the angle of X in polar representation.  This is -PI for
     negative numbers and 0 for positive numbers since Sizzle does not
     support complex numbers.

 - Primitive procedure: real-part z
     Returns the real part of the number Z.  In Sizzle, this returns Z
     itself, because complex numbers are not supported.

 - Primitive procedure: imag-part z
     Returns the imaginary part of the number Z.  The Sizzle
     implementation simply returns 0, because complex numbers are not
     supported.

 - Primitive procedure: numerator q
     Returns the numerator of its argument Q.  Currently, Q itself is
     returned because rational numbers are not supported.

 - Primitive procedure: denominator q
     Returns the denominator of its argument Q.  Currently, 1 is
     returned because rational numbers are not supported.

 - Primitive procedure: quotient n1 n2
     Performs an integer division operation on the two arguments. An
     arithmetic overflow error is signalled if the second operand is
     equal to zero.

 - Primitive procedure: remainder n1 n2
     Returns the rest of an integer division of its arguments. An
     arithmetic overflow error is signalled if the second operand is
     equal to zero.

 - Primitive procedure: modulo n1 n2
     Returns the rest of an integer division of its arguments. An
     arithmetic overflow error is signalled if the second operand is
     equal to zero. This differs from `remainder' as far as negative
     operands ar concerned.

 - Primitive procedure: floor x
     Returns the largest integer not larger than X.

 - Primitive procedure: ceiling x
     Returns the smallest integer not smaller than X.

 - Primitive procedure: truncate x
     Returns the closest integer to X whose absolute value is not
     larger than the absolute value of X.

 - Primitive procedure: round x
     Returns the closest integer to X rounding it to even when X is
     halfway between two integers.

 - Primitive procedure: exp z
     Implements the exponential function.

 - Primitive procedure: log z
     Returns the natural logarithm of Z.

 - Primitive procedure: sin z
     Returns the sine of Z.

 - Primitive procedure: cos z
     Returns the cosine of Z.

 - Primitive procedure: tan z
     Returns the tangent of Z.

 - Primitive procedure: asin z
     Returns the arcsine of Z.

 - Primitive procedure: acos z
     Returns the arccosine of Z.

 - Primitive procedure: atan z
     Returns the arctangent of Z.

 - Primitive procedure: atan y x
     Returns the arctangent of the two variables Y and X. It is similar
     to computing the arctangent of Y / X, except that the signs of
     both arguments are used to determine the quadrant of the result.

 - Primitive procedure: sqrt x
     Returns the square root of its argument. Since complex numbers are
     not supported, X must be positive.

 - Primitive procedure: expt z1 z2
     Returns Z1 raised to the power of Z2.

 - Primitive procedure: exact->inexact z
     Returns Z, converted to an inexact value.

 - Primitive procedure: inexact->exact z
     Returns Z, converted to an exact value. An error signalled if a
     conversion is not possible without losing precision.

 - Primitive procedure: number->string z
 - Primitive procedure: number->string z radix
     Converts its argument to a string.  The radix RADIX is used if
     given.

 - Primitive procedure: string->number string
 - Primitive procedure: string->number string radix
     Converts STRING to a number. When given, RADIX is used as the
     default radix which can be overridden with an explicit radix prefix
     in STRING. `#f' is returned if STRING is not properly formatted.

 - Primitive procedure: lognot n
     Returns the bitwise negated value of the argument.

 - Primitive procedure: logand n ...
     Performs a bitwise _and_ operation on all arguments and returns the
     result. Returns a value with all bits set if called without
     arguments.

 - Primitive procedure: logior n ...
     Performs a bitwise _or_ operation on all arguments and returns the
     result. Returns a value with no bits set if called without
     arguments.

 - Primitive procedure: logxor n ...
     Performs a bitwise _exclusive or_ operation on all arguments and
     returns the result. Returns a value with no bits set if called
     without arguments.

 - Primitive procedure: lsh n1 n2
     Shifts the integer N1 left by N2 bits if N2 is not less than zero,
     or shifts N2 logically right by -N2 bits if N2 is less than zero.

 - Primitive procedure: ash n1 n2
     Shifts the integer N1 left by N2 bits if N2 is not less than zero,
     or shifts N2 arithmetically right by -N2 bits if N2 is less than
     zero.

 - Primitive procedure: gcd [n1 [n2]]
     Returns the greatest common divisor of its arguments.  Without
     arguments, 0 is returned, if only N1 is given, N1 is returned.

 - Primitive procedure: lcm [n1 [n2]]
     Returns the least common multiple of its arguments.  Without
     arguments, 1 is returned, if only N1 is given, N1 is returned.

 - Primitive procedure: signum x
     Return -1 if X is less than zero, 0 if X is equal to zero and 1 if
     Z is greater than zero.


File: sizzle-ref.info,  Node: Boolean operations,  Next: Pair and list operations,  Prev: Numerical operations,  Up: Builtin Procedures

Boolean operations
==================

   The boolean operations documented in this section are always
available.

 - Primitive procedure: boolean? obj
     Returns `#t' if OBJ is a boolean value, `#f' otherwise.

 - Primitive procedure: not obj
     Returns `#t' if OBJ is false, `#f' otherwise.

 - Primitive procedure: boolean->integer b
     Return 0 if B is `#f', 1 otherwise.

 - Primitive procedure: integer->boolean i
     Return `#f' if I is 0, `#t' otherwise.


File: sizzle-ref.info,  Node: Pair and list operations,  Next: Hash table operations,  Prev: Boolean operations,  Up: Builtin Procedures

Pairs and lists
===============

   Sizzle implements all list and pair operations as defined in R5RS,
plus the list operations present in SRFI-1.  All procedures without a
special remark  are available at all times, whereas some procedures
need inclusion of the module `(core list-lib)' prior to usage.

* Menu:

* List constructors::           Creating lists.
* List predicates::             Examining lists.
* List selectors::              Accessing list elements.
* Miscellaneous list procedures::  length, append etc.
* Fold unfold and map::         Fundamental list iterators and constructors
* Filtering and partitioning::  Filtering lists
* List searching::              Searching in lists
* Association lists::           Association lists
* Deletion::                    Deletion of list elements
* Primitive side-effects::      Side-effecting pair manipulation
* Set operations on lists::     Procedures to handle set represented by lists


File: sizzle-ref.info,  Node: List constructors,  Next: List predicates,  Prev: Pair and list operations,  Up: Pair and list operations

List constructors
-----------------

 - Primitive procedure: cons obj1 obj2
     Return a cons cell with a car of OBJ1 and a cdr of OBJ2.

 - Primitive procedure: list obj ...
     Returns a list whose elements are all arguments of the call to
     `list'. With no arguments, the empty list `()' is returned.

 - Primitive procedure: xcons obj1 obj2
     Equivalent to `(cons obj2 obj1)', and is of utility only as a value
     to be conveniently passed to higher-order procedures. (`xcons'
     stands for exchanged cons.)

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: cons* elt1 elt2 ...
     Like `list', but the last argument provides the tail of the
     constructed list.
          (cons* 1 2 3 4) => (1 2 3 . 4)

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: make-list n [fill]
     Return an N-element list, whose elements are all the value FILL.
     If the FILL argument is not given, the elements of the list are
     unspecified.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: list-tabulate n init-proc
     Returns an N-element list. Element I ofthe list, where 0 <= I < N,
     is produced by calling `(init-proc i)'.  The dynamic order in
     which `init-proc' is applied to the indices is not specified.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: list-copy flist
     Copies the spine of the argument list.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: circular-list elt1 elt2 ...
     Constructs a circular list of the elements.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: iota count [start step]
     Returns a list containing the elements
          (start start+step ... start+(count-1)*step)
     The START and STEP parameters default to 0 and 1, respectively.
     This procedure takes its name from the APL primitive.

     This procedure must be imported by using the module `(core
     list-lib)'.


File: sizzle-ref.info,  Node: List predicates,  Next: List selectors,  Prev: List constructors,  Up: Pair and list operations

List predicates
---------------

 - Primitive procedure: list? obj
     Return `#t' if OBJ is a list, `#f' otherwise. Only finite lists
     pass this test, infinite lists return `#f' for this predicate.

 - Primitive procedure: proper-list? x
     Return `#t' if X is a proper list - a finite, nil-terminated list.
     Return #F for any other object.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: circular-list? x
     Return `#t' if X is a circular list.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: dotted-list? x
     Return `#t' if X is a finite, non-nil-terminated list.  This
     includes non-pair, non-() values (e.g. symbols, numbers), which are
     considered to be dotted lists of length 0.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: pair? obj
     Returns `#t' if OBJ is a cons cell, `#f' otherwise.

 - Primitive procedure: null? obj
     Returns `#t' if OBJ is the empty list, `#f' otherwise.

 - Primitive procedure: null-list? list
     LIST is a proper or circular list.  Returns `#t' if the argument
     is the empty list (), and `#f' otherwise.  It is an error to pass
     this procedure a value which is not a proper or circular list.
     This procedure is recommended as the termination condition for
     list-processing procedures that are not defined on dotted lists.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: not-pair? x
     Return `#t' if X is not a pair.  Provided as a procedure as it can
     be useful as the termination condition for list-processing
     procedures that wish to handle all lists, both proper and dotted.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: list= elt= list1 ...
     Determine list equality, given an element-equality procedure.
     Proper list A equals proper list B if they are of the same length
     and their corresponding elements are equal, as determined by ELT=.

     It is an error to apply `list=' to anything except proper lists.

     This procedure must be imported by using the module `(core
     list-lib)'.


File: sizzle-ref.info,  Node: List selectors,  Next: Miscellaneous list procedures,  Prev: List predicates,  Up: Pair and list operations

List selectors
--------------

 - Primitive procedure: car pair
     PAIR must be a cons cell. Return the car of the cons cell PAIR.

 - Primitive procedure: cdr pair
     PAIR must be a cons cell. Return the cdr of the cons cell PAIR.

 - Primitive procedure: caar pair
 - Primitive procedure: cadr pair
 - Primitive procedure: ...
 - Primitive procedure: cdddar pair
 - Primitive procedure: cddddr pair
     These functions are compositions of `car' and `cdr', where for
     example `caddr' could be defined by
          (define caddr (lambda (x) (car (cdr (cdr x)))))
     There are twenty-eight of these functions defined.

 - Primitive procedure: list-ref list k
     Returns the Kth element of LIST. An error is signalled if LIST has
     fewer than K elements.

 - Primitive procedure: list-tail list k
     Returns the sublist of LIST obtained by omitting the first K
     elements.  An error is signalled if LIST has fewer than K elements.

 - Primitive procedure: first pair
 - Primitive procedure: second pair
 - Primitive procedure: third pair
 - Primitive procedure: fourth pair
 - Primitive procedure: fifth pair
 - Primitive procedure: sixth pair
 - Primitive procedure: seventh pair
 - Primitive procedure: eighth pair
 - Primitive procedure: ninth pair
 - Primitive procedure: tenth pair
     Synonyms for `car', `cadr', `caddr', ...

     These procedures must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: car+cdr pair
     The fundamental pair deconstructor.  Return two values, the first
     being the car, the second being the cdr of the pair.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: take list k
     Return a list containing the first K elements of LIST. Return LIST
     if K is larger then the length of LIST.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: drop list k
     Return a list containing the elements of LIST, but without the
     first K elements. Return LIST if K is less or equal to zero,
     returns the empty list if K is larger than the length of LIST.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: take-right flist i
 - Primitive procedure: drop-right flist i
     `take-right' returns the last I elements of FLIST.

     `drop-right' returns all but the last I elements of FLIST.

     The returned list may share a common tail with the argument list.

     These procedures must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: take! x i
 - Primitive procedure: drop-right! x i
     `take!' and `drop-right!' are destructive variants of `take' and
     `drop-right'.  If X is circular, `take!' may return a
     shorter-than-expected list.

     These procedures must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: split-at x i
 - Primitive procedure: split-at! x i
     `split-at' splits the list X at index I, returning two values: a
     list of the first I elements and the remaining tail.

     `split-at!' is the destructive variant of `split-at'.

     These procedures must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: last pair
 - Primitive procedure: last-pair pair
     `last' returns the last element of the non-empty, finite list
     PAIR.  `last-pair' returns the last pair of the non-empty, finite
     list PAIR.


File: sizzle-ref.info,  Node: Miscellaneous list procedures,  Next: Fold unfold and map,  Prev: List selectors,  Up: Pair and list operations

Miscellaneous list procedures
-----------------------------

 - Primitive procedure: length list
 - Primitive procedure: length+ clist
     Returns the length of LIST.  It is an error to pass anything but a
     proper, nil-terminated list to `length'.

     `length+', on the other hand, will return `#f' when applied to a
     circular list.

     `length+' must be imported by using the module `(core list-lib)',
     whereas `length' is always available.

 - Primitive procedure: append list ...
     Returns a list made out of the elements of all argument lists.
     The last argument may be an improper list, an improper list will
     be returned in this case.

 - Primitive procedure: append! list ...
     Destructive version of `append'.  The result of the operation is
     the same as for `append', but as a side effect, the parameter lists
     are modified when performing the append operation.

 - Primitive procedure: concatenate list-of-lists
 - Primitive procedure: concatenate! list-of-lists
     These functions append the elements of their arguments together.
     `concatenate!' may alter the cons cells of the passed lists.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: reverse list
     Returns a newly allocated list with all elements of LIST in
     reversed order.

 - Primitive procedure: reverse! list
     Destructive version of `reverse'.  The result of the operation is
     the same as for `reverse', but as a side effect, the parameter list
     is modified when performing the reverse operation.

 - Procedure procedure: append-reverse rev-head tail
 - Procedure procedure: append-reverse! rev-head tail
     `append-reverse' returns `(append (reverse rev-head) tail)'.  It
     is provided because it is a common operation.

     `append-reverse!' is just the destructive variant.

     These procedures must be imported by using the module `(core
     list-lib)'.

 - Library procedure: zip clist1 clist2 ...
     If zip is passed N lists, it returns a list as long as the
     shortest of these lists, each element of which is an N-element
     lists comprised of the corresponding elements from the parameters
     lists.  At least one of the argument lists must be finite.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Library procedure: unzip1 list
 - Library procedure: unzip2 list
 - Library procedure: unzip3 list
 - Library procedure: unzip4 list
 - Library procedure: unzip5 list
     `unzip1' takes a list of lists, where every list must contain at
     least one element, and returns a list containing the initial
     element of each such list.  That is, it returns `(map car lists)'.

     `unzip2' takes a list of lists, where every list must contain at
     least two elements, and returns two values: a list of the first
     elements and a list of the second elements, `unzip3' does the same
     for the first three elements of the lists, and so forth.
          (unzip2 '((one 1) (two 2) (three 3))) =>
            (1 2 3)
            (one two three)

     These procedures must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: count pred clist1 clist2 ...
     PRED is a procedure taking as many arguments as there are lists
     and returning a single value.  It is applied element-wise to the
     elements of the LISTS, and a count is tallied of the number of
     elements that return a true value. This count is returned.  `count'
     is iterative in that it is guarateed to apply PRED to the LIST
     elements in a left-to-right order.  The counting stops when the
     shortest list expires.  At least one of the argument lists must be
     finite.

     This procedure must be imported by using the module `(core
     list-lib)'.


File: sizzle-ref.info,  Node: Fold unfold and map,  Next: Filtering and partitioning,  Prev: Miscellaneous list procedures,  Up: Pair and list operations

Fold, unfold and map
--------------------

 - Primitive procedure: fold kons knil clist1 clist2 ...
     The fundamental list iterator.

     First, consider the single list-parameter case if clist1=(e1 e2
     ... en) then this procedure returns
          (kons en ... (kons e1 (kons e1 knil)))
     That is, it obeys the (tail) recursion
          (fold kons knil lis) = (fold kons (kons (car lis) knil) (cdr lis))
          (fold kons knil '()) = knil
     If N argument lists are provided, then the KONS procedure must
     take N+1 parameters: one element from each list, and the "seed" or
     fold state, which is initially KNIL.  The fold operation
     terminates when the shortest list runs out of values.  At least
     one of the arhument lists must be finite.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: pair-fold kons knil clist1 clist2 ...
     Analogous to `fold', but KONS is applied to successive sublists of
     the lists, rather than successive elements - that is, KONS is
     applied to the pairs making up the lists.

     For finite lists, the KONS function may reliably apply `set-cdr!'
     to the pairs it is given without altering the sequence of
     execution.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Library procedure: reduce f ridentity list
     `reduce' is a variant of `fold'.

     RIDENTITY should be a "right identity" of the procedure F - that
     is, for any value X acceptable to F,
          (f x ridentity) = x
     Note that RIDENTITY is used only in the empty-list case. You
     typically use `reduce' when applying F is expensive and you'd like
     to avoid the extra application incurred when fol applies F to the
     head of the LIST and the identity value, redundantly producing the
     same value passed to F.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Library procedure: reduce-right f ridentity list
     `reduce-right' is the fold-right variant of `reduce'.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Library procedure: unfold p f g seed [tail-gen]
     `unfold' is defined as follows:
          (unfold p f g seed) =
            (if (p seed) (tail-gen seed)
                         (cons (f seed)
                               (unfold p f g (g seed)))))

    P
          Determines when to stop unfolding.

    F
          Maps each seed value to the corresponding list element.

    G
          Maps each seed value to the next seed value.

    SEED
          The "state" value for the unfold.

    TAIL-GEN
          Creates the tail of the list; defaults to `(lambda (x) '())'.
     In other words, we use G to generate a sequence of seed values
     seed, g(seed), g^2(seed), g^3(seed), ...

     These seed values are mapped to list elements by F, producing the
     elements of the result list in a left-to-right order. P says when
     to stop.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Library procedure: unfold-right p f g seed [tail]
     `unfold-right' constructs a list with the following loop:
          (let lp ((seed seed) (lis tail))
             (if (p seed) lis
                          (lp (g seed) (cons (f seed) lis))))

    P
          Determines when to stop unfolding.

    F
          Maps each seed value to the corresponding list element.

    G
          Maps each seed value to the next seed value.

    SEED
          The "state" value for the unfold.

    TAIL
          List terminator, defaults to `'()'.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: map proc list1 list2 ...
     The LISTS must be lists and PROC must be a procedure taking as
     many arguments as there are LISTS and returning a single value.
     All LISTS must be of the same length. `map' applies PROC
     element-wise to the elements of the LISTS and returns a list of
     the results, in order. The dynamic order in which PROC is applied
     to the elements of the LISTS is unspecified.

 - Primitive procedure: for-each proc list1 list2 ...
     PROC is applied to the elements of the LISTS as with `map', but in
     order. `for-each' is for its side effects of PROC, therefore the
     return value is unspecified.

 - Library procedure: append-map f clist1 clist2 ...
 - Library procedure: append-map! f clist1 clist2 ...
     Map F over the elements of the lists, just as the `map' function.
     However, the results of the applications are appended together to
     make the final result.  `append-map' uses `append' to append the
     results together; `append-map!' uses `append!'. The dynamic order
     in which the various applications of F are made is not specified.

     These procedures must be imported by using the module `(core
     list-lib)'.

 - Library procedure: map! f list clist1 ...
     Destructive variant of `map'.  `map!' may be alter the cons cells
     of list1 to construct the result list.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Library procedure: map-in-order f clist1 clist2 ...
     A variant of the `map' procedure that guarantees to apply F across
     the elements of the list arguments in a left-to-right order.  This
     is useful for mapping procedures that both have side effects and
     return useful values.  At least one of the argument lists must be
     finite.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Library procedure: pair-for-each f clist1 clist2 ...
     Like `for-each', but F is applied to successive sublists of the
     argument lists.  That is, F is applied to the cons cells of the
     lists, rather than the lists' elements.  These applications occur
     in left-to-right order.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Library procedure: filter-map f clist1 clist2 ...
     Like `map', but only true values are saved.  The dynamic order in
     which the various applications of F are made is not specified.  At
     least one of the argument lists must be finite.

     This procedure must be imported by using the module `(core
     list-lib)'.


File: sizzle-ref.info,  Node: Filtering and partitioning,  Next: List searching,  Prev: Fold unfold and map,  Up: Pair and list operations

Filtering and partitioning
--------------------------

 - Library procedure: filter pred list
 - Library procedure: filter! pred list
     Return all the elements of LIST that satisfy predicate PRED.  The
     list is not disordered.  The returned list may share a common tail
     with the argument list.  The dynamic order in which the various
     applications of PRED are made is not specified.

     `filter!' is the destructive variant of `filter'.

     These procedures must be imported by using the module `(core
     list-lib)'.

 - Library procedure: partition pred list
 - Library procedure: partition! pred list
     Partitions the elements of LIST with predicate PRED, and returns
     two values: the list of in-elements and the list of out-elements.
     The list is not disordered. The dynamic order in which the various
     applications of PRED are made is not specified. One of the
     returned lists may share a common tail with the argument list.

     `partition!' is the destructive variant of `partition'.

     These procedures must be imported by using the module `(core
     list-lib)'.

 - Library procedure: remove pred list
 - Library procedure: remove! pred list
     Returns LIST without the elements that satidfy the predicate PRED.
     The list is not disordered. The dynamic order in which the various
     applications of PRED are made is not specified.

     `remove!' is the destructive variant of `remove'.

     These procedures must be imported by using the module `(core
     list-lib)'.


File: sizzle-ref.info,  Node: List searching,  Next: Association lists,  Prev: Filtering and partitioning,  Up: Pair and list operations

List searching
--------------

 - Library procedure: find pred clist
     Return the first element in CLIST that satisfies predicate PRED,
     `#f' if no element does.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Library procedure: find-tail pred clist
     Return the first pair of CLIST whose car satisfies predicate PRED,
     `#f' if no element does.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Library procedure: take-while pred clist
 - Library procedure: take-while! pred clist
     Return the longest initial prefix of CLIST whose elements all
     satisfy the predicate PRED.

     `take-while!' is the destructive variant of `take-while'.

     These procedures must be imported by using the module `(core
     list-lib)'.

 - Library procedure: drop-while pred clist
     Drops the longest initial prefix of CLIST whose elements all
     satisfy the predicate PRED, and returns the rest of the list.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Library procedure: span pred clist
 - Library procedure: span! pred clist
 - Library procedure: break pred clist
 - Library procedure: break! pred clist
     `span' bsplits the list into the longest initial prefix whose
     elements all satisfy PRED, and the remaining tail.  `break'
     inverts the sense of the predicate: the tail commences with the
     first element of the input list that satisfies the predicate.

     `span!' and `break!' are the destructive variants.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Library procedure: any pred clist1 clist2 ...
     Applies the predicated accross the lists, returning true if the
     predicate returns true on any application.  If there are N
     arguments clist1 ... clistn, then PRED must be a procedure taking
     N arguments and returning a boolean result.

     The iteration stops when a true value is produced or one of the
     lists runs out of values, in the latter case, `any' returns `#f'.

     Note the difference between `find' and `any' - `find' returns the
     element that satisfied the predicate, `any' returns the true value
     that the predicate produced.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Library procedure: every pred clist1 clist2 ...
     Applies the predicate across the lists, returning true if the
     predicate returns true on every application.  If there are N
     arguments clist1 ... clistn, then PRED must be a procedure taking
     N arguments and returning a boolean result.

     Like `any', `every''s name does not end with a question mark -
     this is to indicate that it does return a general value, not only
     `#t' or `#f'.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: list-index pred clist1 clist2 ...
     Return the index of the leftmost element that satisfies PRED.  If
     there are N arguments clist1 ... clistn, then PRED must be a
     procedure taking N arguments and returning a boolean result.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: memq obj list
 - Primitive procedure: memv obj list
 - Primitive procedure: member obj list [=]
     These functions return the first sublist of LIST whose car is OBJ.
     `memq' uses `eq?' for comparing the values, `memv' uses `eqv?' and
     `member' uses `equal?'.  If OBJ does not occur in LIST, `#f' is
     returned.

     `member' is extended from R5RS to allow the client to pass an
     optional equality procedure = used to compare keys.


File: sizzle-ref.info,  Node: Association lists,  Next: Deletion,  Prev: List searching,  Up: Pair and list operations

Association lists
-----------------

 - Primitive procedure: assq obj alist
 - Primitive procedure: assv obj alist
 - Primitive procedure: assoc obj alist [=]
     ALIST (for association list) must be a list of pairs. These
     procedures return the first pair in ALIST whose car field is OBJ.
     If no pair in ALIST has OBJ as its car, then `#f' is returned.
     `assq' uses `eq?' for comparing the values, `assv' uses `eqv?' and
     `assoc' uses `equal?'.

     `assoc' is extended from R5RS to allow the client to pass in an
     optional equality procedure = to compare keys.

 - Primitive procedure: alist-cons key datum alist
     Cons a new alist entry mapping from KEY to DATUM onto ALIST.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: alist-copy alist
     Make a fresh copy of ALIST.  This means copying each pair that
     forms an association as well as the spine of the list.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: alist-delete key alist [=]
 - Primitive procedure: alist-delete! key alist [=]
     `alist-delete' deletes all associations from ALIST with the given
     KEY, using key-comparison procedure =, which defaults to `equal?'.
     The dynamic order in which the various applications of = are made
     is not specified.

     `alist-delete!' is the destructive variant of `alist-delete'.  It
     may modify its argument list in order to produce its result.

     This procedure must be imported by using the module `(core
     list-lib)'.


File: sizzle-ref.info,  Node: Deletion,  Next: Primitive side-effects,  Prev: Association lists,  Up: Pair and list operations

Deletion
--------

 - Primitive procedure: delete x list [=]
 - Primitive procedure: delete! x list [=]
     `delete' uses the comparison procedure =, which defaults to
     `equal?', to find all elements of LIST that are equal to X, and
     deletes them from LIST.  The dymanic order in which the various
     applications of = are made is not specified.  The list is not
     disordered - elements that appear in the result list occur in the
     same order as they occur in the argument list.

     `delete!' is the destructive variant of `delete'. It is allowed to
     alter the cons cells in its argument list to construct the result.

     These procedures must be imported by using the module `(core
     list-lib)'.

 - Primitive procedure: delete-duplicates list [=]
 - Primitive procedure: delete-duplicates! list [=]
     `delete-duplicates' removes duplicate elements from the list
     argument.  If there are multiple equal elements in the argument
     list, the result list only contains the first or leftmost of these
     elements in the result.  The order of the surviving elements is
     the same as in the original list.

     `delete-duplicates!' is the destructive variant of
     `delete-duplicates'. It is allowed to alter the argument list to
     produce the result.

     These procedures must be imported by using the module `(core
     list-lib)'.


File: sizzle-ref.info,  Node: Primitive side-effects,  Next: Set operations on lists,  Prev: Deletion,  Up: Pair and list operations

Primitive side-effects
----------------------

 - Primitive procedure: set-car! pair obj
     PAIR must be a cons cell. Sets the car of PAIR to OBJ.  The return
     value is not specified.

 - Primitive procedure: set-cdr! pair obj
     PAIR must be a cons cell. Sets the cdr of PAIR to OBJ.  The return
     value is not specified.


File: sizzle-ref.info,  Node: Set operations on lists,  Prev: Primitive side-effects,  Up: Pair and list operations

Set operations on lists
-----------------------

 - Library procedure: lset<= = list1 ...
     Returns true iff every LIST_I is a subset of LIST_I+1, using = for
     the element-equality procedure.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Library procedure: lset= = list1 ...
     Returns true iff every LIST_I is a set-equal of LIST_I+1, using =
     for the element-equality procedure.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Library procedure: lset-adjoin = list elt1 ...
     Adds the ELTS not already in the list parameter to the result
     list.  The result shares a common tail with the list parameter.
     The = parameter is an equality procedure used to determine of an
     ELT_I is already a member of LIST.

     The list parameter is always a suffix of the result - even if the
     list parameter contains repeated elements, these are not reduced.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Library procedure: lset-union = list1 ...
     Returns the union of the lists, using = for the element-equality
     procedure.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Library procedure: lset-intersection = list1 ...
     Returns the intersection of the lists, using = for the
     element-equality procedure.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Library procedure: lset-difference = list1 list2 ...
     Returns the intersection of the lists, using = for the
     element-equality procedure.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Library procedure: lset-xor = list1 ...
     Returns the exclusive-or of the sets, using = for the
     element-equality procedure.  The result is a list of all elements
     which appear in an odd number of the parameter LISTS.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Library procedure: lset-diff+intersection = list1 list2 ...
     Returns two values - the difference and the intersection of the
     lists.

     This procedure must be imported by using the module `(core
     list-lib)'.

 - Library procedure: lset-union! = list1 ...
 - Library procedure: lset-intersection! = list1 list2 ...
 - Library procedure: lset-difference! = list1 list2 ...
 - Library procedure: lset-xor! = list1 ...
 - Library procedure: lset-diff+intersection! = list1 list2 ...
     These are destructive variants of the pure functions.

     These procedures must be imported by using the module `(core
     list-lib)'.

