
% Copyright (c) 1991-2002, The Numerical ALgorithms Group Ltd.
% All rights reserved.
%
% Redistribution and use in source and binary forms, with or without
% modification, are permitted provided that the following conditions are
% met:
%
%     - Redistributions of source code must retain the above copyright
%       notice, this list of conditions and the following disclaimer.
%
%     - Redistributions in binary form must reproduce the above copyright
%       notice, this list of conditions and the following disclaimer in
%       the documentation and/or other materials provided with the
%       distribution.
%
%     - Neither the name of The Numerical ALgorithms Group Ltd. nor the
%       names of its contributors may be used to endorse or promote products
%       derived from this software without specific prior written permission.
%
% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
% IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
% TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
% PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
% OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
% EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
% PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES-- LOSS OF USE, DATA, OR
% PROFITS-- OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
% LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
% NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
% SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.



% vector.htex
% Author: Clifton J. Williamson

The \spadtype{Vector} domain is used for storing data in a one-dimensional
indexed data structure.
A vector is a homogeneous data structure in that all the components of the
vector must belong to the same \Language{} domain.
Each vector has a fixed length specified by the user; vectors are not
extensible.
This domain is similar to the \spadtype{OneDimensionalArray} domain,
except that when the components of a \spadtype{Vector} belong to a
\spadtype{Ring}, arithmetic operations are provided.
For more examples of operations that are defined for both
\spadtype{Vector} and \spadtype{OneDimensionalArray}, see
\xmpref{OneDimensionalArray}.

As with the \spadtype{OneDimensionalArray} domain, a \spadtype{Vector} can
be created by calling the operation \spadfunFrom{new}{Vector}, its components
can be accessed by calling the operations \spadfunFrom{elt}{Vector} and
\spadfunFrom{qelt}{Vector}, and its components can be reset by calling the
operations \spadfunFrom{setelt!}{Vector} and
\spadfunFromX{qsetelt}{Vector}.
\xtc{
This creates a vector of integers of length
\spad{5} all of whose components are \spad{12}.
}{
\spadcommand{u : VECTOR INT := new(5,12) \bound{u}}
}
\xtc{
This is how you create a vector from a list of its components.
}{
\spadcommand{v : VECTOR INT := vector([1,2,3,4,5]) \bound{v}}
}

\xtc{
Indexing for vectors begins at \spad{1}.
The last element has index equal to the length of the vector,
which is computed by \spadopFrom{\#}{Vector}.
}{
\spadcommand{\#(v) \free{v}}
}
\xtc{
This is the standard way to use \spadfunFrom{elt}{Vector} to extract an
element.
Functionally, it is the same as if you had typed \spad{elt(v,2)}.
}{
\spadcommand{v.2 \free{v}}
}
\xtc{
This is the standard way to use \spadfunFrom{setelt!}{Vector} to change an
element.
It is the same as if you had typed \spad{setelt!(v, 3, 99)}.
}{
\spadcommand{v.3 := 99 \free{v}\bound{vdelta}}
}
\xtc{
Now look at \spad{v} to see the change.
You can
use \spadfunFrom{qelt}{Vector} and \spadfunFromX{qsetelt}{Vector} (instead
of \spadfunFrom{elt}{Vector} and \spadfunFrom{setelt!}{Vector},
respectively) but {\it only} when you know that the index is within the valid
range.
}{
\spadcommand{v \free{vdelta}}
}

\xtc{
When the components belong to a \spadtype{Ring}, \Language{}
provides arithmetic operations for \spadtype{Vector}.
These include left and right scalar multiplication.
}{
\spadcommand{5 * v \free{vdelta}}
}
\xtc{
}{
\spadcommand{v * 7 \free{vdelta}}
}
\xtc{
}{
\spadcommand{w : VECTOR INT := vector([2,3,4,5,6]) \bound{w}}
}
\xtc{
Addition and subtraction are also available.
}{
\spadcommand{v + w \free{vdelta w}}
}
\xtc{
Of course, when adding or subtracting, the two vectors must have the same
length or an error message is displayed.
}{
\spadcommand{v - w \free{vdelta w}}
}

For more information about other aggregate domains,
see the following:
\xmpref{List},
\xmpref{Matrix},
\xmpref{OneDimensionalArray},
\xmpref{Set},
\xmpref{Table}, and
\xmpref{TwoDimensionalArray}.
Issue the system command \spadcmd{)show Vector}
to display the full list of operations defined by
\spadtype{Vector}.
