   Guile Reference Manual Copyright (C) 1996 Free Software Foundation
Copyright (C) 1997 Free Software Foundation
Copyright (C) 2000 Free Software Foundation
Copyright (C) 2001 Free Software Foundation
Copyright (C) 2002 Free Software Foundation

   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.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.

Symbols as Lookup Keys
----------------------

   Given their efficiency and descriptive power, it is natural to use
symbols as the keys in an association list or hash table.

   To illustrate this, consider a more structured representation of the
car properties example from the preceding subsection.  Rather than
mixing all the properties up together in a flat list, we could use an
association list like this:

     (define car1-properties '((colour . red)
                               (transmission . manual)
                               (fuel . unleaded)
                               (steering . power-assisted)))

   Notice how this structure is more explicit and extensible than the
flat list.  For example it makes clear that `manual' refers to the
transmission rather than, say, the windows or the locking of the car.
It also allows further properties to use the same symbols among their
possible values without becoming ambiguous:

     (define car1-properties '((colour . red)
                               (transmission . manual)
                               (fuel . unleaded)
                               (steering . power-assisted)
                               (seat-colour . red)
                               (locking . manual)))

   With a representation like this, it is easy to use the efficient
`assq-XXX' family of procedures (see Association Lists) to extract
or change individual pieces of information:

     (assq-ref car1-properties 'fuel) => unleaded
     (assq-ref car1-properties 'transmission) => manual

     (assq-set! car1-properties 'seat-colour 'black)
     =>
     ((colour . red)
      (transmission . manual)
      (fuel . unleaded)
      (steering . power-assisted)
      (seat-colour . black)
      (locking . manual)))

   Hash tables also have keys, and exactly the same arguments apply to
the use of symbols in hash tables as in association lists.  The hash
value that Guile uses to decide where to add a symbol-keyed entry to a
hash table can be obtained by calling the `symbol-hash' procedure:

 - Scheme Procedure: symbol-hash symbol
 - C Function: scm_symbol_hash (symbol)
     Return a hash value for SYMBOL.

   See Hash Tables for information about hash tables in
general, and for why you might choose to use a hash table rather than
an association list.

Symbols as Denoting Variables
-----------------------------

   When an unquoted symbol in a Scheme program is evaluated, it is
interpreted as a variable reference, and the result of the evaluation is
the appropriate variable's value.

   For example, when the expression `(string-length "abcd")' is read
and evaluated, the sequence of characters `string-length' is read as
the symbol whose name is "string-length".  This symbol is associated
with a variable whose value is the procedure that implements string
length calculation.  Therefore evaluation of the `string-length' symbol
results in that procedure.

   The details of the connection between an unquoted symbol and the
variable to which it refers are explained elsewhere.  See Binding Constructs,
for how associations between symbols and variables are
created, and Modules, for how those associations are affected by
Guile's module system.

Operations Related to Symbols
-----------------------------

   Given any Scheme value, you can determine whether it is a symbol
using the `symbol?' primitive:

 - Scheme Procedure: symbol? obj
 - C Function: scm_symbol_p (obj)
     Return `#t' if OBJ is a symbol, otherwise return `#f'.

   Once you know that you have a symbol, you can obtain its name as a
string by calling `symbol->string'.  Note that Guile differs by default
from R5RS on the details of `symbol->string' as regards
case-sensitivity:

 - Scheme Procedure: symbol->string s
 - C Function: scm_symbol_to_string (s)
     Return the name of symbol S as a string.  By default, Guile reads
     symbols case-sensitively, so the string returned will have the
     same case variation as the sequence of characters that caused S to
     be created.

     If Guile is set to read symbols case-insensitively (as specified by
     R5RS), and S comes into being as part of a literal expression
     (see Literal expressions (r5rs)) or by a
     call to the `read' or `string-ci->symbol' procedures, Guile
     converts any alphabetic characters in the symbol's name to lower
     case before creating the symbol object, so the string returned
     here will be in lower case.

     If S was created by `string->symbol', the case of characters in
     the string returned will be the same as that in the string that was
     passed to `string->symbol', regardless of Guile's case-sensitivity
     setting at the time S was created.

     It is an error to apply mutation procedures like `string-set!' to
     strings returned by this procedure.

   Most symbols are created by writing them literally in code.  However
it is also possible to create symbols programmatically using the
following `string->symbol' and `string-ci->symbol' procedures:

 - Scheme Procedure: string->symbol string
 - C Function: scm_string_to_symbol (string)
     Return the symbol whose name is STRING.  This procedure can create
     symbols with names containing special characters or letters in the
     non-standard case, but it is usually a bad idea to create such
     symbols because in some implementations of Scheme they cannot be
     read as themselves.

 - Scheme Procedure: string-ci->symbol str
 - C Function: scm_string_ci_to_symbol (str)
     Return the symbol whose name is STR.  If Guile is currently
     reading symbols case-insensitively, STR is converted to lowercase
     before the returned symbol is looked up or created.

   The following examples illustrate Guile's detailed behaviour as
regards the case-sensitivity of symbols:

     (read-enable 'case-insensitive)   ; R5RS compliant behaviour

     (symbol->string 'flying-fish)    => "flying-fish"
     (symbol->string 'Martin)         => "martin"
     (symbol->string
        (string->symbol "Malvina"))   => "Malvina"

     (eq? 'mISSISSIppi 'mississippi)  => #t
     (string->symbol "mISSISSIppi")   => mISSISSIppi
     (eq? 'bitBlt (string->symbol "bitBlt")) => #f
     (eq? 'LolliPop
       (string->symbol (symbol->string 'LolliPop))) => #t
     (string=? "K. Harper, M.D."
       (symbol->string
         (string->symbol "K. Harper, M.D."))) => #t

     (read-disable 'case-insensitive)   ; Guile default behaviour

     (symbol->string 'flying-fish)    => "flying-fish"
     (symbol->string 'Martin)         => "Martin"
     (symbol->string
        (string->symbol "Malvina"))   => "Malvina"

     (eq? 'mISSISSIppi 'mississippi)  => #f
     (string->symbol "mISSISSIppi")   => mISSISSIppi
     (eq? 'bitBlt (string->symbol "bitBlt")) => #t
     (eq? 'LolliPop
       (string->symbol (symbol->string 'LolliPop))) => #t
     (string=? "K. Harper, M.D."
       (symbol->string
         (string->symbol "K. Harper, M.D."))) => #t

   Finally, some applications, especially those that generate new Scheme
code dynamically, need to generate symbols for use in the generated
code.  The `gensym' primitive meets this need:

 - Scheme Procedure: gensym [prefix]
 - C Function: scm_gensym (prefix)
     Create a new symbol with a name constructed from a prefix and a
     counter value.  The string PREFIX can be specified as an optional
     argument.  Default prefix is ` g'.  The counter is increased by 1
     at each call.  There is no provision for resetting the counter.

   The symbols generated by `gensym' are _likely_ to be unique, since
their names begin with a space and it is only otherwise possible to
generate such symbols if a programmer goes out of their way to do so.
The 1.8 release of Guile will include a way of creating symbols that
are _guaranteed_ to be unique.

Function Slots and Property Lists
---------------------------------

   In traditional Lisp dialects, symbols are often understood as having
three kinds of value at once:

   * a "variable" value, which is used when the symbol appears in code
     in a variable reference context

   * a "function" value, which is used when the symbol appears in code
     in a function name position (i.e. as the first element in an
     unquoted list)

   * a "property list" value, which is used when the symbol is given as
     the first argument to Lisp's `put' or `get' functions.

   Although Scheme (as one of its simplifications with respect to Lisp)
does away with the distinction between variable and function namespaces,
Guile currently retains some elements of the traditional structure in
case they turn out to be useful when implementing translators for other
languages, in particular Emacs Lisp.

   Specifically, Guile symbols have two extra slots. for a symbol's
property list, and for its "function value."  The following procedures
are provided to access these slots.

 - Scheme Procedure: symbol-fref symbol
 - C Function: scm_symbol_fref (symbol)
     Return the contents of SYMBOL's "function slot".

 - Scheme Procedure: symbol-fset! symbol value
 - C Function: scm_symbol_fset_x (symbol, value)
     Set the contents of SYMBOL's function slot to VALUE.

 - Scheme Procedure: symbol-pref symbol
 - C Function: scm_symbol_pref (symbol)
     Return the "property list" currently associated with SYMBOL.

 - Scheme Procedure: symbol-pset! symbol value
 - C Function: scm_symbol_pset_x (symbol, value)
     Set SYMBOL's property list to VALUE.

 - Scheme Procedure: symbol-property sym prop
     From SYM's property list, return the value for property PROP.  The
     assumption is that SYM's property list is an association list
     whose keys are distinguished from each other using `equal?'; PROP
     should be one of the keys in that list.  If the property list has
     no entry for PROP, `symbol-property' returns `#f'.

 - Scheme Procedure: set-symbol-property! sym prop val
     In SYM's property list, set the value for property PROP to VAL, or
     add a new entry for PROP, with value VAL, if none already exists.
     For the structure of the property list, see `symbol-property'.

 - Scheme Procedure: symbol-property-remove! sym prop
     From SYM's property list, remove the entry for property PROP, if
     there is one.  For the structure of the property list, see
     `symbol-property'.

   Support for these extra slots may be removed in a future release,
and it is probably better to avoid using them.  (In release 1.6, Guile
itself uses the property list slot sparingly, and the function slot not
at all.)  For a more modern and Schemely approach to properties, see
Object Properties.

Extended Read Syntax for Symbols
--------------------------------

   The read syntax for a symbol is a sequence of letters, digits, and
"extended alphabetic characters", beginning with a character that
cannot begin a number.  In addition, the special cases of `+', `-', and
`...' are read as symbols even though numbers can begin with `+', `-'
or `.'.

   Extended alphabetic characters may be used within identifiers as if
they were letters.  The set of extended alphabetic characters is:

     ! $ % & * + - . / : < = > ? @ ^ _ ~

   In addition to the standard read syntax defined above (which is taken
from R5RS (see Formal syntax (r5rs))), Guile provides
an extended symbol read syntax that allows the inclusion of unusual
characters such as space characters, newlines and parentheses.  If (for
whatever reason) you need to write a symbol containing characters not
mentioned above, you can do so as follows.

   * Begin the symbol with the characters `#{',

   * write the characters of the symbol and

   * finish the symbol with the characters `}#'.

   Here are a few examples of this form of read syntax.  The first
symbol needs to use extended syntax because it contains a space
character, the second because it contains a line break, and the last
because it looks like a number.

     #{foo bar}#

     #{what
     ever}#

     #{4242}#

   Although Guile provides this extended read syntax for symbols,
widespread usage of it is discouraged because it is not portable and not
very readable.

Keywords
========

   Keywords are self-evaluating objects with a convenient read syntax
that makes them easy to type.

   Guile's keyword support conforms to R5RS, and adds a (switchable)
read syntax extension to permit keywords to begin with `:' as well as
`#:'.

Why Use Keywords?
-----------------

   Keywords are useful in contexts where a program or procedure wants
to be able to accept a large number of optional arguments without
making its interface unmanageable.

   To illustrate this, consider a hypothetical `make-window' procedure,
which creates a new window on the screen for drawing into using some
graphical toolkit.  There are many parameters that the caller might
like to specify, but which could also be sensibly defaulted, for
example:

   * color depth - Default: the color depth for the screen

   * background color - Default: white

   * width - Default: 600

   * height - Default: 400

   If `make-window' did not use keywords, the caller would have to pass
in a value for each possible argument, remembering the correct argument
order and using a special value to indicate the default value for that
argument:

     (make-window 'default              ;; Color depth
                  'default              ;; Background color
                  800                   ;; Width
                  100                   ;; Height
                  ...)                  ;; More make-window arguments

   With keywords, on the other hand, defaulted arguments are omitted,
and non-default arguments are clearly tagged by the appropriate
keyword.  As a result, the invocation becomes much clearer:

     (make-window #:width 800 #:height 100)

   On the other hand, for a simpler procedure with few arguments, the
use of keywords would be a hindrance rather than a help.  The primitive
procedure `cons', for example, would not be improved if it had to be
invoked as

     (cons #:car x #:cdr y)

   So the decision whether to use keywords or not is purely pragmatic:
use them if they will clarify the procedure invocation at point of call.

Coding With Keywords
--------------------

   If a procedure wants to support keywords, it should take a rest
argument and then use whatever means is convenient to extract keywords
and their corresponding arguments from the contents of that rest
argument.

   The following example illustrates the principle: the code for
`make-window' uses a helper procedure called `get-keyword-value' to
extract individual keyword arguments from the rest argument.

     (define (get-keyword-value args keyword default)
       (let ((kv (memq keyword args)))
         (if (and kv (>= (length kv) 2))
             (cadr kv)
             default)))

     (define (make-window . args)
       (let ((depth  (get-keyword-value args #:depth  screen-depth))
             (bg     (get-keyword-value args #:bg     "white"))
             (width  (get-keyword-value args #:width  800))
             (height (get-keyword-value args #:height 100))
             ...)
         ...))

   But you don't need to write `get-keyword-value'.  The `(ice-9
optargs)' module provides a set of powerful macros that you can use to
implement keyword-supporting procedures like this:

     (use-modules (ice-9 optargs))

     (define (make-window . args)
       (let-keywords args #f ((depth  screen-depth)
                              (bg     "white")
                              (width  800)
                              (height 100))
         ...))

Or, even more economically, like this:

     (use-modules (ice-9 optargs))

     (define* (make-window #:key (depth  screen-depth)
                                 (bg     "white")
                                 (width  800)
                                 (height 100))
       ...)

   For further details on `let-keywords', `define*' and other
facilities provided by the `(ice-9 optargs)' module, see Optional Arguments.

Keyword Read Syntax
-------------------

   Guile, by default, only recognizes the keyword syntax specified by
R5RS.  A token of the form `#:NAME', where `NAME' has the same syntax
as a Scheme symbol (see Symbol Read Syntax), is the external
representation of the keyword named `NAME'.  Keyword objects print
using this syntax as well, so values containing keyword objects can be
read back into Guile.  When used in an expression, keywords are
self-quoting objects.

   If the `keyword' read option is set to `'prefix', Guile also
recognizes the alternative read syntax `:NAME'.  Otherwise, tokens of
the form `:NAME' are read as symbols, as required by R5RS.

   To enable and disable the alternative non-R5RS keyword syntax, you
use the `read-set!' procedure documented in User level options interfaces
and Reader options.

     (read-set! keywords 'prefix)

     #:type
     =>
     #:type

     :type
     =>
     #:type

     (read-set! keywords #f)

     #:type
     =>
     #:type

     :type
     -|
     ERROR: In expression :type:
     ERROR: Unbound variable: :type
     ABORT: (unbound-variable)

Keyword Procedures
------------------

   The following procedures can be used for converting symbols to
keywords and back.

 - Scheme Procedure: symbol->keyword sym
     Return a keyword with the same characters as in SYM.

 - Scheme Procedure: keyword->symbol kw
     Return a symbol with the same characters as in KW.

Keyword Primitives
------------------

   Internally, a keyword is implemented as something like a tagged
symbol, where the tag identifies the keyword as being self-evaluating,
and the symbol, known as the keyword's "dash symbol" has the same name
as the keyword name but prefixed by a single dash.  For example, the
keyword `#:name' has the corresponding dash symbol `-name'.

   Most keyword objects are constructed automatically by the reader
when it reads a token beginning with `#:'.  However, if you need to
construct a keyword object programmatically, you can do so by calling
`make-keyword-from-dash-symbol' with the corresponding dash symbol (as
the reader does).  The dash symbol for a keyword object can be
retrieved using the `keyword-dash-symbol' procedure.

 - Scheme Procedure: make-keyword-from-dash-symbol symbol
 - C Function: scm_make_keyword_from_dash_symbol (symbol)
     Make a keyword object from a SYMBOL that starts with a dash.

 - Scheme Procedure: keyword? obj
 - C Function: scm_keyword_p (obj)
     Return `#t' if the argument OBJ is a keyword, else `#f'.

 - Scheme Procedure: keyword-dash-symbol keyword
 - C Function: scm_keyword_dash_symbol (keyword)
     Return the dash symbol for KEYWORD.  This is the inverse of
     `make-keyword-from-dash-symbol'.

"Functionality-Centric" Data Types
==================================

   Procedures and macros are documented in their own chapter: see
Procedures and Macros.

   Variable objects are documented as part of the description of Guile's
module system: see Variables.

   Asyncs, dynamic roots and fluids are described in the chapter on
scheduling: see Scheduling.

   Hooks are documented in the chapter on general utility functions: see
Hooks.

   Ports are described in the chapter on I/O: see Input and Output.

Compound Data Types
*******************

   This chapter describes Guile's compound data types.  By "compound"
we mean that the primary purpose of these data types is to act as
containers for other kinds of data (including other compound objects).
For instance, a (non-uniform) vector with length 5 is a container that
can hold five arbitrary Scheme objects.

   The various kinds of container object differ from each other in how
their memory is allocated, how they are indexed, and how particular
values can be looked up within them.

Pairs
=====

   Pairs are used to combine two Scheme objects into one compound
object.  Hence the name: A pair stores a pair of objects.

   The data type "pair" is extremely important in Scheme, just like in
any other Lisp dialect.  The reason is that pairs are not only used to
make two values available as one object, but that pairs are used for
constructing lists of values.  Because lists are so important in Scheme,
they are described in a section of their own (see Lists).

   Pairs can literally get entered in source code or at the REPL, in the
so-called "dotted list" syntax.  This syntax consists of an opening
parentheses, the first element of the pair, a dot, the second element
and a closing parentheses.  The following example shows how a pair
consisting of the two numbers 1 and 2, and a pair containing the symbols
`foo' and `bar' can be entered.  It is very important to write the
whitespace before and after the dot, because otherwise the Scheme
parser would not be able to figure out where to split the tokens.

     (1 . 2)
     (foo . bar)

   But beware, if you want to try out these examples, you have to
"quote" the expressions.  More information about quotation is available
in the section (REFFIXME).  The correct way to try these examples is as
follows.

     '(1 . 2)
     =>
     (1 . 2)
     '(foo . bar)
     =>
     (foo . bar)

   A new pair is made by calling the procedure `cons' with two
arguments.  Then the argument values are stored into a newly allocated
pair, and the pair is returned.  The name `cons' stands for
"construct".  Use the procedure `pair?' to test whether a given Scheme
object is a pair or not.

 - Scheme Procedure: cons x y
 - C Function: scm_cons (x, y)
     Return a newly allocated pair whose car is X and whose cdr is Y.
     The pair is guaranteed to be different (in the sense of `eq?')
     from every previously existing object.

 - Scheme Procedure: pair? x
 - C Function: scm_pair_p (x)
     Return `#t' if X is a pair; otherwise return `#f'.

   The two parts of a pair are traditionally called "car" and "cdr".
They can be retrieved with procedures of the same name (`car' and
`cdr'), and can be modified with the procedures `set-car!' and
`set-cdr!'.  Since a very common operation in Scheme programs is to
access the car of a pair, or the car of the cdr of a pair, etc., the
procedures called `caar', `cadr' and so on are also predefined.

 - Scheme Procedure: car pair
 - Scheme Procedure: cdr pair
     Return the car or the cdr of PAIR, respectively.

 - Scheme Procedure: caar pair
 - Scheme Procedure: cadr pair ...
 - Scheme Procedure: cdddar pair
 - Scheme Procedure: cddddr pair
     These procedures are compositions of `car' and `cdr', where for
     example `caddr' could be defined by

          (define caddr (lambda (x) (car (cdr (cdr x)))))

 - Scheme Procedure: set-car! pair value
 - C Function: scm_set_car_x (pair, value)
     Stores VALUE in the car field of PAIR.  The value returned by
     `set-car!' is unspecified.

 - Scheme Procedure: set-cdr! pair value
 - C Function: scm_set_cdr_x (pair, value)
     Stores VALUE in the cdr field of PAIR.  The value returned by
     `set-cdr!' is unspecified.

Lists
=====

   A very important data type in Scheme--as well as in all other Lisp
dialects--is the data type "list".(1)

   This is the short definition of what a list is:

   * Either the empty list `()',

   * or a pair which has a list in its cdr.

   ---------- Footnotes ----------

   (1) Strictly speaking, Scheme does not have a real datatype "list".
Lists are made up of "chained pairs", and only exist by definition--a
list is a chain of pairs which looks like a list.

List Read Syntax
----------------

   The syntax for lists is an opening parentheses, then all the
elements of the list (separated by whitespace) and finally a closing
parentheses.(1).

     (1 2 3)            ; a list of the numbers 1, 2 and 3
     ("foo" bar 3.1415) ; a string, a symbol and a real number
     ()                 ; the empty list

   The last example needs a bit more explanation.  A list with no
elements, called the "empty list", is special in some ways.  It is used
for terminating lists by storing it into the cdr of the last pair that
makes up a list.  An example will clear that up:

     (car '(1))
     =>
     1
     (cdr '(1))
     =>
     ()

   This example also shows that lists have to be quoted (REFFIXME) when
written, because they would otherwise be mistakingly taken as procedure
applications (see Simple Invocation).

   ---------- Footnotes ----------

   (1) Note that there is no separation character between the list
elements, like a comma or a semicolon.

List Predicates
---------------

   Often it is useful to test whether a given Scheme object is a list or
not.  List-processing procedures could use this information to test
whether their input is valid, or they could do different things
depending on the datatype of their arguments.

 - Scheme Procedure: list? x
 - C Function: scm_list_p (x)
     Return `#t' iff X is a proper list, else `#f'.

   The predicate `null?' is often used in list-processing code to tell
whether a given list has run out of elements.  That is, a loop somehow
deals with the elements of a list until the list satisfies `null?'.
Then, the algorithm terminates.

 - Scheme Procedure: null? x
 - C Function: scm_null_p (x)
     Return `#t' iff X is the empty list, else `#f'.

List Constructors
-----------------

   This section describes the procedures for constructing new lists.
`list' simply returns a list where the elements are the arguments,
`cons*' is similar, but the last argument is stored in the cdr of the
last pair of the list.

 - Scheme Procedure: list . objs
 - C Function: scm_list (objs)
     Return a list containing OBJS, the arguments to `list'.

 - Scheme Procedure: cons* arg1 arg2 ...
 - C Function: scm_cons_star (arg1, rest)
     Like `list', but the last arg provides the tail of the constructed
     list, returning `(cons ARG1 (cons ARG2 (cons ... ARGN)))'.
     Requires at least one argument.  If given one argument, that
     argument is returned as result.  This function is called `list*'
     in some other Schemes and in Common LISP.

 - Scheme Procedure: list-copy lst
 - C Function: scm_list_copy (lst)
     Return a (newly-created) copy of LST.

 - Scheme Procedure: make-list n [init]
     Create a list containing of N elements, where each element is
     initialized to INIT.  INIT defaults to the empty list `()' if not
     given.

   Note that `list-copy' only makes a copy of the pairs which make up
the spine of the lists.  The list elements are not copied, which means
that modifying the elements of the new list also modifies the elements
of the old list.  On the other hand, applying procedures like
`set-cdr!' or `delv!' to the new list will not alter the old list.  If
you also need to copy the list elements (making a deep copy), use the
procedure `copy-tree' (see Copying).

List Selection
--------------

   These procedures are used to get some information about a list, or to
retrieve one or more elements of a list.

 - Scheme Procedure: length lst
 - C Function: scm_length (lst)
     Return the number of elements in list LST.

 - Scheme Procedure: last-pair lst
 - C Function: scm_last_pair (lst)
     Return a pointer to the last pair in LST, signalling an error if
     LST is circular.

 - Scheme Procedure: list-ref list k
 - C Function: scm_list_ref (list, k)
     Return the Kth element from LIST.

 - Scheme Procedure: list-tail lst k
 - Scheme Procedure: list-cdr-ref lst k
 - C Function: scm_list_tail (lst, k)
     Return the "tail" of LST beginning with its Kth element.  The
     first element of the list is considered to be element 0.

     `list-tail' and `list-cdr-ref' are identical.  It may help to
     think of `list-cdr-ref' as accessing the Kth cdr of the list, or
     returning the results of cdring K times down LST.

 - Scheme Procedure: list-head lst k
 - C Function: scm_list_head (lst, k)
     Copy the first K elements from LST into a new list, and return it.

Append and Reverse
------------------

   `append' and `append!' are used to concatenate two or more lists in
order to form a new list.  `reverse' and `reverse!' return lists with
the same elements as their arguments, but in reverse order.  The
procedure variants with an `!' directly modify the pairs which form the
list, whereas the other procedures create new pairs.  This is why you
should be careful when using the side-effecting variants.

 - Scheme Procedure: append . args
 - C Function: scm_append (args)
     Return a list consisting of the elements the lists passed as
     arguments.
          (append '(x) '(y))          =>  (x y)
          (append '(a) '(b c d))      =>  (a b c d)
          (append '(a (b)) '((c)))    =>  (a (b) (c))
     The resulting list is always newly allocated, except that it
     shares structure with the last list argument.  The last argument
     may actually be any object; an improper list results if the last
     argument is not a proper list.
          (append '(a b) '(c . d))    =>  (a b c . d)
          (append '() 'a)             =>  a

 - Scheme Procedure: append! . lists
 - C Function: scm_append_x (lists)
     A destructive version of `append' (see Pairs and lists (r5rs)).
     The cdr field of each list's final pair
     is changed to point to the head of the next list, so no consing is
     performed.  Return a pointer to the mutated list.

 - Scheme Procedure: reverse lst
 - C Function: scm_reverse (lst)
     Return a new list that contains the elements of LST but in reverse
     order.

 - Scheme Procedure: reverse! lst [new_tail]
 - C Function: scm_reverse_x (lst, new_tail)
     A destructive version of `reverse' (see Pairs and lists (r5rs)).
     The cdr of each cell in LST is modified
     to point to the previous list element.  Return a pointer to the
     head of the reversed list.

     Caveat: because the list is modified in place, the tail of the
     original list now becomes its head, and the head of the original
     list now becomes the tail.  Therefore, the LST symbol to which the
     head of the original list was bound now points to the tail.  To
     ensure that the head of the modified list is not lost, it is wise
     to save the return value of `reverse!'

List Modification
-----------------

   The following procedures modify an existing list, either by changing
elements of the list, or by changing the list structure itself.

 - Scheme Procedure: list-set! list k val
 - C Function: scm_list_set_x (list, k, val)
     Set the Kth element of LIST to VAL.

 - Scheme Procedure: list-cdr-set! list k val
 - C Function: scm_list_cdr_set_x (list, k, val)
     Set the Kth cdr of LIST to VAL.

 - Scheme Procedure: delq item lst
 - C Function: scm_delq (item, lst)
     Return a newly-created copy of LST with elements `eq?' to ITEM
     removed.  This procedure mirrors `memq': `delq' compares elements
     of LST against ITEM with `eq?'.

 - Scheme Procedure: delv item lst
 - C Function: scm_delv (item, lst)
     Return a newly-created copy of LST with elements `eqv?'  to ITEM
     removed.  This procedure mirrors `memv': `delv' compares elements
     of LST against ITEM with `eqv?'.

 - Scheme Procedure: delete item lst
 - C Function: scm_delete (item, lst)
     Return a newly-created copy of LST with elements `equal?'  to ITEM
     removed.  This procedure mirrors `member': `delete' compares
     elements of LST against ITEM with `equal?'.

 - Scheme Procedure: delq! item lst
 - Scheme Procedure: delv! item lst
 - Scheme Procedure: delete! item lst
 - C Function: scm_delq_x (item, lst)
 - C Function: scm_delv_x (item, lst)
 - C Function: scm_delete_x (item, lst)
     These procedures are destructive versions of `delq', `delv' and
     `delete': they modify the pointers in the existing LST rather than
     creating a new list.  Caveat evaluator: Like other destructive
     list functions, these functions cannot modify the binding of LST,
     and so cannot be used to delete the first element of LST
     destructively.

 - Scheme Procedure: delq1! item lst
 - C Function: scm_delq1_x (item, lst)
     Like `delq!', but only deletes the first occurrence of ITEM from
     LST.  Tests for equality using `eq?'.  See also `delv1!' and
     `delete1!'.

 - Scheme Procedure: delv1! item lst
 - C Function: scm_delv1_x (item, lst)
     Like `delv!', but only deletes the first occurrence of ITEM from
     LST.  Tests for equality using `eqv?'.  See also `delq1!' and
     `delete1!'.

 - Scheme Procedure: delete1! item lst
 - C Function: scm_delete1_x (item, lst)
     Like `delete!', but only deletes the first occurrence of ITEM from
     LST.  Tests for equality using `equal?'.  See also `delq1!' and
     `delv1!'.

List Searching
--------------

   The following procedures search lists for particular elements.  They
use different comparison predicates for comparing list elements with the
object to be searched.  When they fail, they return `#f', otherwise
they return the sublist whose car is equal to the search object, where
equality depends on the equality predicate used.

 - Scheme Procedure: memq x lst
 - C Function: scm_memq (x, lst)
     Return the first sublist of LST whose car is `eq?' to X where the
     sublists of LST are the non-empty lists returned by `(list-tail
     LST K)' for K less than the length of LST.  If X does not occur in
     LST, then `#f' (not the empty list) is returned.

 - Scheme Procedure: memv x lst
 - C Function: scm_memv (x, lst)
     Return the first sublist of LST whose car is `eqv?' to X where the
     sublists of LST are the non-empty lists returned by `(list-tail
     LST K)' for K less than the length of LST.  If X does not occur in
     LST, then `#f' (not the empty list) is returned.

 - Scheme Procedure: member x lst
 - C Function: scm_member (x, lst)
     Return the first sublist of LST whose car is `equal?' to X where
     the sublists of LST are the non-empty lists returned by
     `(list-tail LST K)' for K less than the length of LST.  If X does
     not occur in LST, then `#f' (not the empty list) is returned.

List Mapping
------------

   List processing is very convenient in Scheme because the process of
iterating over the elements of a list can be highly abstracted.  The
procedures in this section are the most basic iterating procedures for
lists.  They take a procedure and one or more lists as arguments, and
apply the procedure to each element of the list.  They differ in their
return value.

 - Scheme Procedure: map proc arg1 arg2 ...
 - Scheme Procedure: map-in-order proc arg1 arg2 ...
 - C Function: scm_map (proc, arg1, args)
     Apply PROC to each element of the list ARG1 (if only two arguments
     are given), or to the corresponding elements of the argument lists
     (if more than two arguments are given).  The result(s) of the
     procedure applications are saved and returned in a list.  For
     `map', the order of procedure applications is not specified,
     `map-in-order' applies the procedure from left to right to the list
     elements.

 - Scheme Procedure: for-each proc arg1 arg2 ...
     Like `map', but the procedure is always applied from left to right,
     and the result(s) of the procedure applications are thrown away.
     The return value is not specified.

Vectors
=======

   Vectors are sequences of Scheme objects.  Unlike lists, the length
of a vector, once the vector is created, cannot be changed.  The
advantage of vectors over lists is that the time required to access one
element of a vector given its "position" (synonymous with "index"), a
zero-origin number, is constant, whereas lists have an access time
linear to the position of the accessed element in the list.

   Vectors can contain any kind of Scheme object; it is even possible
to have different types of objects in the same vector.  For vectors
containing vectors, you may wish to use arrays, instead.  Note, too,
that some array procedures operate happily on vectors (see Arrays).

Read Syntax for Vectors
-----------------------

   Vectors can literally be entered in source code, just like strings,
characters or some of the other data types.  The read syntax for vectors
is as follows: A sharp sign (`#'), followed by an opening parentheses,
all elements of the vector in their respective read syntax, and finally
a closing parentheses.  The following are examples of the read syntax
for vectors; where the first vector only contains numbers and the
second three different object types: a string, a symbol and a number in
hexadecimal notation.

     #(1 2 3)
     #("Hello" foo #xdeadbeef)

Dynamic Vector Creation and Validation
--------------------------------------

   Instead of creating a vector implicitly by using the read syntax just
described, you can create a vector dynamically by calling one of the
`vector' and `list->vector' primitives with the list of Scheme values
that you want to place into a vector.  The size of the vector thus
created is determined implicitly by the number of arguments given.

 - Scheme Procedure: vector . l
 - Scheme Procedure: list->vector l
 - C Function: scm_vector (l)
     Return a newly allocated vector composed of the given arguments.
     Analogous to `list'.

          (vector 'a 'b 'c) => #(a b c)

   (As an aside, an interesting implementation detail is that the Guile
reader reads the `#(...)' syntax by reading everything but the initial
`#' as a _list_, and then passing the list that results to
`list->vector'.  Notice how neatly this fits with the similarity
between the read (and print) syntaxes for lists and vectors.)

   The inverse operation is `vector->list':

 - Scheme Procedure: vector->list v
 - C Function: scm_vector_to_list (v)
     Return a newly allocated list composed of the elements of V.

          (vector->list '#(dah dah didah)) =>  (dah dah didah)
          (list->vector '(dididit dah)) =>  #(dididit dah)

   To allocate a vector with an explicitly specified size, use
`make-vector'.  With this primitive you can also specify an initial
value for the vector elements (the same value for all elements, that
is):

 - Scheme Procedure: make-vector k [fill]
 - C Function: scm_make_vector (k, fill)
     Return a newly allocated vector of K elements.  If a second
     argument is given, then each position is initialized to FILL.
     Otherwise the initial contents of each position is unspecified.

   To check whether an arbitrary Scheme value _is_ a vector, use the
`vector?' primitive:

 - Scheme Procedure: vector? obj
 - C Function: scm_vector_p (obj)
     Return `#t' if OBJ is a vector, otherwise return `#f'.

Accessing and Modifying Vector Contents
---------------------------------------

   `vector-length' and `vector-ref' return information about a given
vector, respectively its size and the elements that are contained in
the vector.

 - Scheme Procedure: vector-length vector
 - C Function: scm_vector_length vector
     Return the number of elements in VECTOR as an exact integer.

 - Scheme Procedure: vector-ref vector k
 - C Function: scm_vector_ref vector k
     Return the contents of position K of VECTOR.  K must be a valid
     index of VECTOR.
          (vector-ref '#(1 1 2 3 5 8 13 21) 5) => 8
          (vector-ref '#(1 1 2 3 5 8 13 21)
              (let ((i (round (* 2 (acos -1)))))
                (if (inexact? i)
                  (inexact->exact i)
                     i))) => 13

   A vector created by one of the dynamic vector constructor procedures
(see Vector Creation) can be modified using the following
procedures.

   _NOTE:_ According to R5RS, it is an error to use any of these
procedures on a literally read vector, because such vectors should be
considered as constants.  Currently, however, Guile does not detect this
error.

 - Scheme Procedure: vector-set! vector k obj
 - C Function: scm_vector_set_x vector k obj
     Store OBJ in position K of VECTOR.  K must be a valid index of
     VECTOR.  The value returned by `vector-set!' is unspecified.
          (let ((vec (vector 0 '(2 2 2 2) "Anna")))
            (vector-set! vec 1 '("Sue" "Sue"))
            vec) =>  #(0 ("Sue" "Sue") "Anna")

 - Scheme Procedure: vector-fill! v fill
 - C Function: scm_vector_fill_x (v, fill)
     Store FILL in every position of VECTOR.  The value returned by
     `vector-fill!' is unspecified.

 - Scheme Procedure: vector-move-left! vec1 start1 end1 vec2 start2
 - C Function: scm_vector_move_left_x (vec1, start1, end1, vec2, start2)
     Copy elements from VEC1, positions START1 to END1, to VEC2
     starting at position START2.  START1 and START2 are inclusive
     indices; END1 is exclusive.

     `vector-move-left!' copies elements in leftmost order.  Therefore,
     in the case where VEC1 and VEC2 refer to the same vector,
     `vector-move-left!' is usually appropriate when START1 is greater
     than START2.

 - Scheme Procedure: vector-move-right! vec1 start1 end1 vec2 start2
 - C Function: scm_vector_move_right_x (vec1, start1, end1, vec2,
          start2)
     Copy elements from VEC1, positions START1 to END1, to VEC2
     starting at position START2.  START1 and START2 are inclusive
     indices; END1 is exclusive.

     `vector-move-right!' copies elements in rightmost order.
     Therefore, in the case where VEC1 and VEC2 refer to the same
     vector, `vector-move-right!' is usually appropriate when START1 is
     less than START2.