merge from 1.8 branch

[bpt/guile.git] / doc / ref / api-compound.texi

@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@page
@node Compound Data Types
@section Compound Data Types

This chapter describes Guile's compound data types.  By @dfn{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.

@menu
* Pairs::                       Scheme's basic building block.
* Lists::                       Special list functions supported by Guile.
* Vectors::                     One-dimensional arrays of Scheme objects.
* Uniform Numeric Vectors::     Vectors with elements of a single numeric type.
* Bit Vectors::                 Vectors of bits.
* Generalized Vectors::         Treating all vector-like things uniformly.
* Arrays::                      Matrices, etc.
* Records::                     
* Structures::                  
* Dictionary Types::            About dictionary types in general.
* Association Lists::           List-based dictionaries.
* Hash Tables::                 Table-based dictionaries.
@end menu


@node Pairs
@subsection Pairs
@tpindex 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 @dfn{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 (@pxref{Lists}).

Pairs can literally get entered in source code or at the REPL, in the
so-called @dfn{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
@code{foo} and @code{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.

@lisp
(1 . 2)
(foo . bar)
@end lisp

But beware, if you want to try out these examples, you have to
@dfn{quote} the expressions.  More information about quotation is
available in the section @ref{Expression Syntax}.  The correct way
to try these examples is as follows.

@lisp
'(1 . 2)
@result{}
(1 . 2)
'(foo . bar)
@result{}
(foo . bar)
@end lisp

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

@rnindex cons
@deffn {Scheme Procedure} cons x y
@deffnx {C Function} scm_cons (x, y)
Return a newly allocated pair whose car is @var{x} and whose
cdr is @var{y}.  The pair is guaranteed to be different (in the
sense of @code{eq?}) from every previously existing object.
@end deffn

@rnindex pair?
@deffn {Scheme Procedure} pair? x
@deffnx {C Function} scm_pair_p (x)
Return @code{#t} if @var{x} is a pair; otherwise return
@code{#f}.
@end deffn

@deftypefn {C Function} int scm_is_pair (SCM x)
Return 1 when @var{x} is a pair; otherwise return 0.
@end deftypefn

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

@rnindex car
@rnindex cdr
@deffn {Scheme Procedure} car pair
@deffnx {Scheme Procedure} cdr pair
@deffnx {C Function} scm_car (pair)
@deffnx {C Function} scm_cdr (pair)
Return the car or the cdr of @var{pair}, respectively.
@end deffn

@deftypefn  {C Macro} SCM SCM_CAR (SCM pair)
@deftypefnx {C Macro} SCM SCM_CDR (SCM pair)
These two macros are the fastest way to access the car or cdr of a
pair; they can be thought of as compiling into a single memory
reference.

These macros do no checking at all.  The argument @var{pair} must be a
valid pair.
@end deftypefn

@deffn  {Scheme Procedure} cddr pair
@deffnx {Scheme Procedure} cdar pair
@deffnx {Scheme Procedure} cadr pair
@deffnx {Scheme Procedure} caar pair
@deffnx {Scheme Procedure} cdddr pair
@deffnx {Scheme Procedure} cddar pair
@deffnx {Scheme Procedure} cdadr pair
@deffnx {Scheme Procedure} cdaar pair
@deffnx {Scheme Procedure} caddr pair
@deffnx {Scheme Procedure} cadar pair
@deffnx {Scheme Procedure} caadr pair
@deffnx {Scheme Procedure} caaar pair
@deffnx {Scheme Procedure} cddddr pair
@deffnx {Scheme Procedure} cdddar pair
@deffnx {Scheme Procedure} cddadr pair
@deffnx {Scheme Procedure} cddaar pair
@deffnx {Scheme Procedure} cdaddr pair
@deffnx {Scheme Procedure} cdadar pair
@deffnx {Scheme Procedure} cdaadr pair
@deffnx {Scheme Procedure} cdaaar pair
@deffnx {Scheme Procedure} cadddr pair
@deffnx {Scheme Procedure} caddar pair
@deffnx {Scheme Procedure} cadadr pair
@deffnx {Scheme Procedure} cadaar pair
@deffnx {Scheme Procedure} caaddr pair
@deffnx {Scheme Procedure} caadar pair
@deffnx {Scheme Procedure} caaadr pair
@deffnx {Scheme Procedure} caaaar pair
@deffnx {C Function} scm_cddr (pair)
@deffnx {C Function} scm_cdar (pair)
@deffnx {C Function} scm_cadr (pair)
@deffnx {C Function} scm_caar (pair)
@deffnx {C Function} scm_cdddr (pair)
@deffnx {C Function} scm_cddar (pair)
@deffnx {C Function} scm_cdadr (pair)
@deffnx {C Function} scm_cdaar (pair)
@deffnx {C Function} scm_caddr (pair)
@deffnx {C Function} scm_cadar (pair)
@deffnx {C Function} scm_caadr (pair)
@deffnx {C Function} scm_caaar (pair)
@deffnx {C Function} scm_cddddr (pair)
@deffnx {C Function} scm_cdddar (pair)
@deffnx {C Function} scm_cddadr (pair)
@deffnx {C Function} scm_cddaar (pair)
@deffnx {C Function} scm_cdaddr (pair)
@deffnx {C Function} scm_cdadar (pair)
@deffnx {C Function} scm_cdaadr (pair)
@deffnx {C Function} scm_cdaaar (pair)
@deffnx {C Function} scm_cadddr (pair)
@deffnx {C Function} scm_caddar (pair)
@deffnx {C Function} scm_cadadr (pair)
@deffnx {C Function} scm_cadaar (pair)
@deffnx {C Function} scm_caaddr (pair)
@deffnx {C Function} scm_caadar (pair)
@deffnx {C Function} scm_caaadr (pair)
@deffnx {C Function} scm_caaaar (pair)
These procedures are compositions of @code{car} and @code{cdr}, where
for example @code{caddr} could be defined by

@lisp
(define caddr (lambda (x) (car (cdr (cdr x)))))
@end lisp
@end deffn

@rnindex set-car!
@deffn {Scheme Procedure} set-car! pair value
@deffnx {C Function} scm_set_car_x (pair, value)
Stores @var{value} in the car field of @var{pair}.  The value returned
by @code{set-car!} is unspecified.
@end deffn

@rnindex set-cdr!
@deffn {Scheme Procedure} set-cdr! pair value
@deffnx {C Function} scm_set_cdr_x (pair, value)
Stores @var{value} in the cdr field of @var{pair}.  The value returned
by @code{set-cdr!} is unspecified.
@end deffn


@node Lists
@subsection Lists
@tpindex Lists

A very important data type in Scheme---as well as in all other Lisp
dialects---is the data type @dfn{list}.@footnote{Strictly speaking,
Scheme does not have a real datatype @dfn{list}.  Lists are made up of
@dfn{chained pairs}, and only exist by definition---a list is a chain
of pairs which looks like a list.}

This is the short definition of what a list is:

@itemize @bullet
@item
Either the empty list @code{()},

@item
or a pair which has a list in its cdr.
@end itemize

@c FIXME::martin: Describe the pair chaining in more detail.

@c FIXME::martin: What is a proper, what an improper list?
@c What is a circular list?

@c FIXME::martin: Maybe steal some graphics from the Elisp reference 
@c manual?

@menu
* List Syntax::                 Writing literal lists.
* List Predicates::             Testing lists.
* List Constructors::           Creating new lists.
* List Selection::              Selecting from lists, getting their length.
* Append/Reverse::              Appending and reversing lists.
* List Modification::           Modifying existing lists.
* List Searching::              Searching for list elements
* List Mapping::                Applying procedures to lists.
@end menu

@node List Syntax
@subsubsection 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.@footnote{Note that there is no separation character between
the list elements, like a comma or a semicolon.}.

@lisp
(1 2 3)            ; @r{a list of the numbers 1, 2 and 3}
("foo" bar 3.1415) ; @r{a string, a symbol and a real number}
()                 ; @r{the empty list}
@end lisp

The last example needs a bit more explanation.  A list with no elements,
called the @dfn{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:

@lisp
(car '(1))
@result{}
1
(cdr '(1))
@result{}
()
@end lisp

This example also shows that lists have to be quoted when written
(@pxref{Expression Syntax}), because they would otherwise be
mistakingly taken as procedure applications (@pxref{Simple
Invocation}).


@node List Predicates
@subsubsection 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.

@rnindex list?
@deffn {Scheme Procedure} list? x
@deffnx {C Function} scm_list_p (x)
Return @code{#t} iff @var{x} is a proper list, else @code{#f}.
@end deffn

The predicate @code{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
@code{null?}.  Then, the algorithm terminates.

@rnindex null?
@deffn {Scheme Procedure} null? x
@deffnx {C Function} scm_null_p (x)
Return @code{#t} iff @var{x} is the empty list, else @code{#f}.
@end deffn

@deftypefn {C Function} int scm_is_null (SCM x)
Return 1 when @var{x} is the empty list; otherwise return 0.
@end deftypefn


@node List Constructors
@subsubsection List Constructors

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

@c  C Function scm_list(rest) used to be documented here, but it's a
@c  no-op since it does nothing but return the list the caller must
@c  have already created.
@c
@deffn {Scheme Procedure} list elem1 @dots{} elemN
@deffnx {C Function} scm_list_1 (elem1)
@deffnx {C Function} scm_list_2 (elem1, elem2)
@deffnx {C Function} scm_list_3 (elem1, elem2, elem3)
@deffnx {C Function} scm_list_4 (elem1, elem2, elem3, elem4)
@deffnx {C Function} scm_list_5 (elem1, elem2, elem3, elem4, elem5)
@deffnx {C Function} scm_list_n (elem1, @dots{}, elemN, @nicode{SCM_UNDEFINED})
@rnindex list
Return a new list containing elements @var{elem1} to @var{elemN}.

@code{scm_list_n} takes a variable number of arguments, terminated by
the special @code{SCM_UNDEFINED}.  That final @code{SCM_UNDEFINED} is
not included in the list.  None of @var{elem1} to @var{elemN} can
themselves be @code{SCM_UNDEFINED}, or @code{scm_list_n} will
terminate at that point.
@end deffn

@c  C Function scm_cons_star(arg1,rest) used to be documented here,
@c  but it's not really a useful interface, since it expects the
@c  caller to have already consed up all but the first argument
@c  already.
@c
@deffn {Scheme Procedure} cons* arg1 arg2 @dots{}
Like @code{list}, but the last arg provides the tail of the
constructed list, returning @code{(cons @var{arg1} (cons
@var{arg2} (cons @dots{} @var{argn})))}.  Requires at least one
argument.  If given one argument, that argument is returned as
result.  This function is called @code{list*} in some other
Schemes and in Common LISP.
@end deffn

@deffn {Scheme Procedure} list-copy lst
@deffnx {C Function} scm_list_copy (lst)
Return a (newly-created) copy of @var{lst}.
@end deffn

@deffn {Scheme Procedure} make-list n [init]
Create a list containing of @var{n} elements, where each element is
initialized to @var{init}.  @var{init} defaults to the empty list
@code{()} if not given.
@end deffn

Note that @code{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
@code{set-cdr!} or @code{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 @code{copy-tree} (@pxref{Copying}).

@node List Selection
@subsubsection List Selection

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

@rnindex length
@deffn {Scheme Procedure} length lst
@deffnx {C Function} scm_length (lst)
Return the number of elements in list @var{lst}.
@end deffn

@deffn {Scheme Procedure} last-pair lst
@deffnx {C Function} scm_last_pair (lst)
Return the last pair in @var{lst}, signalling an error if
@var{lst} is circular.
@end deffn

@rnindex list-ref
@deffn {Scheme Procedure} list-ref list k
@deffnx {C Function} scm_list_ref (list, k)
Return the @var{k}th element from @var{list}.
@end deffn

@rnindex list-tail
@deffn {Scheme Procedure} list-tail lst k
@deffnx {Scheme Procedure} list-cdr-ref lst k
@deffnx {C Function} scm_list_tail (lst, k)
Return the "tail" of @var{lst} beginning with its @var{k}th element.
The first element of the list is considered to be element 0.

@code{list-tail} and @code{list-cdr-ref} are identical.  It may help to
think of @code{list-cdr-ref} as accessing the @var{k}th cdr of the list,
or returning the results of cdring @var{k} times down @var{lst}.
@end deffn

@deffn {Scheme Procedure} list-head lst k
@deffnx {C Function} scm_list_head (lst, k)
Copy the first @var{k} elements from @var{lst} into a new list, and
return it.
@end deffn

@node Append/Reverse
@subsubsection Append and Reverse

@code{append} and @code{append!} are used to concatenate two or more
lists in order to form a new list.  @code{reverse} and @code{reverse!}
return lists with the same elements as their arguments, but in reverse
order.  The procedure variants with an @code{!} 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.

@rnindex append
@deffn {Scheme Procedure} append lst1 @dots{} lstN
@deffnx {Scheme Procedure} append! lst1 @dots{} lstN
@deffnx {C Function} scm_append (lstlst)
@deffnx {C Function} scm_append_x (lstlst)
Return a list comprising all the elements of lists @var{lst1} to
@var{lstN}.

@lisp
(append '(x) '(y))          @result{}  (x y)
(append '(a) '(b c d))      @result{}  (a b c d)
(append '(a (b)) '((c)))    @result{}  (a (b) (c))
@end lisp

The last argument @var{lstN} may actually be any object; an improper
list results if the last argument is not a proper list.

@lisp
(append '(a b) '(c . d))    @result{}  (a b c . d)
(append '() 'a)             @result{}  a
@end lisp

@code{append} doesn't modify the given lists, but the return may share
structure with the final @var{lstN}.  @code{append!} modifies the
given lists to form its return.

For @code{scm_append} and @code{scm_append_x}, @var{lstlst} is a list
of the list operands @var{lst1} @dots{} @var{lstN}.  That @var{lstlst}
itself is not modified or used in the return.
@end deffn

@rnindex reverse
@deffn {Scheme Procedure} reverse lst
@deffnx {Scheme Procedure} reverse! lst [newtail]
@deffnx {C Function} scm_reverse (lst)
@deffnx {C Function} scm_reverse_x (lst, newtail)
Return a list comprising the elements of @var{lst}, in reverse order.

@code{reverse} constructs a new list, @code{reverse!} modifies
@var{lst} in constructing its return.

For @code{reverse!}, the optional @var{newtail} is appended to to the
result.  @var{newtail} isn't reversed, it simply becomes the list
tail.  For @code{scm_reverse_x}, the @var{newtail} parameter is
mandatory, but can be @code{SCM_EOL} if no further tail is required.
@end deffn

@node List Modification
@subsubsection List Modification

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

@deffn {Scheme Procedure} list-set! list k val
@deffnx {C Function} scm_list_set_x (list, k, val)
Set the @var{k}th element of @var{list} to @var{val}.
@end deffn

@deffn {Scheme Procedure} list-cdr-set! list k val
@deffnx {C Function} scm_list_cdr_set_x (list, k, val)
Set the @var{k}th cdr of @var{list} to @var{val}.
@end deffn

@deffn {Scheme Procedure} delq item lst
@deffnx {C Function} scm_delq (item, lst)
Return a newly-created copy of @var{lst} with elements
@code{eq?} to @var{item} removed.  This procedure mirrors
@code{memq}: @code{delq} compares elements of @var{lst} against
@var{item} with @code{eq?}.
@end deffn

@deffn {Scheme Procedure} delv item lst
@deffnx {C Function} scm_delv (item, lst)
Return a newly-created copy of @var{lst} with elements
@code{eqv?}  to @var{item} removed.  This procedure mirrors
@code{memv}: @code{delv} compares elements of @var{lst} against
@var{item} with @code{eqv?}.
@end deffn

@deffn {Scheme Procedure} delete item lst
@deffnx {C Function} scm_delete (item, lst)
Return a newly-created copy of @var{lst} with elements
@code{equal?}  to @var{item} removed.  This procedure mirrors
@code{member}: @code{delete} compares elements of @var{lst}
against @var{item} with @code{equal?}.
@end deffn

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

@deffn {Scheme Procedure} delq1! item lst
@deffnx {C Function} scm_delq1_x (item, lst)
Like @code{delq!}, but only deletes the first occurrence of
@var{item} from @var{lst}.  Tests for equality using
@code{eq?}.  See also @code{delv1!} and @code{delete1!}.
@end deffn

@deffn {Scheme Procedure} delv1! item lst
@deffnx {C Function} scm_delv1_x (item, lst)
Like @code{delv!}, but only deletes the first occurrence of
@var{item} from @var{lst}.  Tests for equality using
@code{eqv?}.  See also @code{delq1!} and @code{delete1!}.
@end deffn

@deffn {Scheme Procedure} delete1! item lst
@deffnx {C Function} scm_delete1_x (item, lst)
Like @code{delete!}, but only deletes the first occurrence of
@var{item} from @var{lst}.  Tests for equality using
@code{equal?}.  See also @code{delq1!} and @code{delv1!}.
@end deffn

@deffn {Scheme Procedure} filter pred lst
@deffnx {Scheme Procedure} filter! pred lst
Return a list containing all elements from @var{lst} which satisfy the
predicate @var{pred}.  The elements in the result list have the same
order as in @var{lst}.  The order in which @var{pred} is applied to
the list elements is not specified.

@code{filter} does not change @var{lst}, but the result may share a
tail with it.  @code{filter!} may modify @var{lst} to construct its
return.
@end deffn

@node List Searching
@subsubsection 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 @code{#f}, otherwise
they return the sublist whose car is equal to the search object, where
equality depends on the equality predicate used.

@rnindex memq
@deffn {Scheme Procedure} memq x lst
@deffnx {C Function} scm_memq (x, lst)
Return the first sublist of @var{lst} whose car is @code{eq?}
to @var{x} where the sublists of @var{lst} are the non-empty
lists returned by @code{(list-tail @var{lst} @var{k})} for
@var{k} less than the length of @var{lst}.  If @var{x} does not
occur in @var{lst}, then @code{#f} (not the empty list) is
returned.
@end deffn

@rnindex memv
@deffn {Scheme Procedure} memv x lst
@deffnx {C Function} scm_memv (x, lst)
Return the first sublist of @var{lst} whose car is @code{eqv?}
to @var{x} where the sublists of @var{lst} are the non-empty
lists returned by @code{(list-tail @var{lst} @var{k})} for
@var{k} less than the length of @var{lst}.  If @var{x} does not
occur in @var{lst}, then @code{#f} (not the empty list) is
returned.
@end deffn

@rnindex member
@deffn {Scheme Procedure} member x lst
@deffnx {C Function} scm_member (x, lst)
Return the first sublist of @var{lst} whose car is
@code{equal?} to @var{x} where the sublists of @var{lst} are
the non-empty lists returned by @code{(list-tail @var{lst}
@var{k})} for @var{k} less than the length of @var{lst}.  If
@var{x} does not occur in @var{lst}, then @code{#f} (not the
empty list) is returned.
@end deffn


@node List Mapping
@subsubsection 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.

@rnindex map
@c begin (texi-doc-string "guile" "map")
@deffn {Scheme Procedure} map proc arg1 arg2 @dots{}
@deffnx {Scheme Procedure} map-in-order proc arg1 arg2 @dots{}
@deffnx {C Function} scm_map (proc, arg1, args)
Apply @var{proc} to each element of the list @var{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
@code{map}, the order of procedure applications is not specified,
@code{map-in-order} applies the procedure from left to right to the list
elements.
@end deffn

@rnindex for-each
@c begin (texi-doc-string "guile" "for-each")
@deffn {Scheme Procedure} for-each proc arg1 arg2 @dots{}
Like @code{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.
@end deffn


@node Vectors
@subsection Vectors
@tpindex 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 @dfn{position} (synonymous with @dfn{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 vectors are the special case of one dimensional non-uniform arrays
and that most array procedures operate happily on vectors
(@pxref{Arrays}).

@menu
* Vector Syntax::               Read syntax for vectors.
* Vector Creation::             Dynamic vector creation and validation.
* Vector Accessors::            Accessing and modifying vector contents.
* Vector Accessing from C::     Ways to work with vectors from C.
@end menu


@node Vector Syntax
@subsubsection 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 (@code{#}), 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.

@lisp
#(1 2 3)
#("Hello" foo #xdeadbeef)
@end lisp

Like lists, vectors have to be quoted:

@lisp
'#(a b c) @result{} #(a b c)
@end lisp

@node Vector Creation
@subsubsection 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
@code{vector} and @code{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.

@rnindex vector
@rnindex list->vector
@deffn {Scheme Procedure} vector . l
@deffnx {Scheme Procedure} list->vector l
@deffnx {C Function} scm_vector (l)
Return a newly allocated vector composed of the
given arguments.  Analogous to @code{list}.

@lisp
(vector 'a 'b 'c) @result{} #(a b c)
@end lisp
@end deffn

The inverse operation is @code{vector->list}:

@rnindex vector->list
@deffn {Scheme Procedure} vector->list v
@deffnx {C Function} scm_vector_to_list (v)
Return a newly allocated list composed of the elements of @var{v}.

@lisp
(vector->list '#(dah dah didah)) @result{}  (dah dah didah)
(list->vector '(dididit dah)) @result{}  #(dididit dah)
@end lisp
@end deffn

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

@rnindex make-vector
@deffn {Scheme Procedure} make-vector len [fill]
@deffnx {C Function} scm_make_vector (len, fill)
Return a newly allocated vector of @var{len} elements.  If a
second argument is given, then each position is initialized to
@var{fill}.  Otherwise the initial contents of each position is
unspecified.
@end deffn

@deftypefn {C Function} SCM scm_c_make_vector (size_t k, SCM fill)
Like @code{scm_make_vector}, but the length is given as a @code{size_t}.
@end deftypefn

To check whether an arbitrary Scheme value @emph{is} a vector, use the
@code{vector?} primitive:

@rnindex vector?
@deffn {Scheme Procedure} vector? obj
@deffnx {C Function} scm_vector_p (obj)
Return @code{#t} if @var{obj} is a vector, otherwise return
@code{#f}.
@end deffn

@deftypefn {C Function} int scm_is_vector (SCM obj)
Return non-zero when @var{obj} is a vector, otherwise return
@code{zero}.
@end deftypefn

@node Vector Accessors
@subsubsection Accessing and Modifying Vector Contents

@code{vector-length} and @code{vector-ref} return information about a
given vector, respectively its size and the elements that are contained
in the vector.

@rnindex vector-length
@deffn {Scheme Procedure} vector-length vector
@deffnx {C Function} scm_vector_length vector
Return the number of elements in @var{vector} as an exact integer.
@end deffn

@deftypefn {C Function} size_t scm_c_vector_length (SCM v)
Return the number of elements in @var{vector} as a @code{size_t}.
@end deftypefn

@rnindex vector-ref
@deffn {Scheme Procedure} vector-ref vector k
@deffnx {C Function} scm_vector_ref vector k
Return the contents of position @var{k} of @var{vector}.
@var{k} must be a valid index of @var{vector}.
@lisp
(vector-ref '#(1 1 2 3 5 8 13 21) 5) @result{} 8
(vector-ref '#(1 1 2 3 5 8 13 21)
    (let ((i (round (* 2 (acos -1)))))
      (if (inexact? i)
        (inexact->exact i)
           i))) @result{} 13
@end lisp
@end deffn

@deftypefn {C Function} SCM scm_c_vector_ref (SCM v, size_t k)
Return the contents of position @var{k} (a @code{size_t}) of
@var{vector}.
@end deftypefn

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

@emph{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.

@rnindex vector-set!
@deffn {Scheme Procedure} vector-set! vector k obj
@deffnx {C Function} scm_vector_set_x vector k obj
Store @var{obj} in position @var{k} of @var{vector}.
@var{k} must be a valid index of @var{vector}.
The value returned by @samp{vector-set!} is unspecified.
@lisp
(let ((vec (vector 0 '(2 2 2 2) "Anna")))
  (vector-set! vec 1 '("Sue" "Sue"))
  vec) @result{}  #(0 ("Sue" "Sue") "Anna")
@end lisp
@end deffn

@deftypefn {C Function} void scm_c_vector_set_x (SCM v, size_t k, SCM obj)
Store @var{obj} in position @var{k} (a @code{size_t}) of @var{v}.
@end deftypefn

@rnindex vector-fill!
@deffn {Scheme Procedure} vector-fill! v fill
@deffnx {C Function} scm_vector_fill_x (v, fill)
Store @var{fill} in every position of @var{vector}.  The value
returned by @code{vector-fill!} is unspecified.
@end deffn

@deffn {Scheme Procedure} vector-copy vec
@deffnx {C Function} scm_vector_copy (vec)
Return a copy of @var{vec}.
@end deffn

@deffn {Scheme Procedure} vector-move-left! vec1 start1 end1 vec2 start2
@deffnx {C Function} scm_vector_move_left_x (vec1, start1, end1, vec2, start2)
Copy elements from @var{vec1}, positions @var{start1} to @var{end1},
to @var{vec2} starting at position @var{start2}.  @var{start1} and
@var{start2} are inclusive indices; @var{end1} is exclusive.

@code{vector-move-left!} copies elements in leftmost order.
Therefore, in the case where @var{vec1} and @var{vec2} refer to the
same vector, @code{vector-move-left!} is usually appropriate when
@var{start1} is greater than @var{start2}.
@end deffn

@deffn {Scheme Procedure} vector-move-right! vec1 start1 end1 vec2 start2
@deffnx {C Function} scm_vector_move_right_x (vec1, start1, end1, vec2, start2)
Copy elements from @var{vec1}, positions @var{start1} to @var{end1},
to @var{vec2} starting at position @var{start2}.  @var{start1} and
@var{start2} are inclusive indices; @var{end1} is exclusive.

@code{vector-move-right!} copies elements in rightmost order.
Therefore, in the case where @var{vec1} and @var{vec2} refer to the
same vector, @code{vector-move-right!} is usually appropriate when
@var{start1} is less than @var{start2}.
@end deffn

@node Vector Accessing from C
@subsubsection Vector Accessing from C

A vector can be read and modified from C with the functions
@code{scm_c_vector_ref} and @code{scm_c_vector_set_x}, for example.  In
addition to these functions, there are two more ways to access vectors
from C that might be more efficient in certain situations: you can
restrict yourself to @dfn{simple vectors} and then use the very fast
@emph{simple vector macros}; or you can use the very general framework
for accessing all kinds of arrays (@pxref{Accessing Arrays from C}),
which is more verbose, but can deal efficiently with all kinds of
vectors (and arrays).  For vectors, you can use the
@code{scm_vector_elements} and @code{scm_vector_writable_elements}
functions as shortcuts.

@deftypefn {C Function} int scm_is_simple_vector (SCM obj)
Return non-zero if @var{obj} is a simple vector, else return zero.  A
simple vector is a vector that can be used with the @code{SCM_SIMPLE_*}
macros below.

The following functions are guaranteed to return simple vectors:
@code{scm_make_vector}, @code{scm_c_make_vector}, @code{scm_vector},
@code{scm_list_to_vector}.
@end deftypefn

@deftypefn {C Macro} size_t SCM_SIMPLE_VECTOR_LENGTH (SCM vec)
Evaluates to the length of the simple vector @var{vec}.  No type
checking is done.
@end deftypefn

@deftypefn {C Macro} SCM SCM_SIMPLE_VECTOR_REF (SCM vec, size_t idx)
Evaluates to the element at position @var{idx} in the simple vector
@var{vec}.  No type or range checking is done.
@end deftypefn

@deftypefn {C Macro} void SCM_SIMPLE_VECTOR_SET (SCM vec, size_t idx, SCM val)
Sets the element at position @var{idx} in the simple vector
@var{vec} to @var{val}.  No type or range checking is done.
@end deftypefn

@deftypefn {C Function} {const SCM *} scm_vector_elements (SCM vec, scm_t_array_handle *handle, size_t *lenp, ssize_t *incp)