
% 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.



The \spadtype{TwoDimensionalArray} domain is used for storing data in a
\index{array!two-dimensional}
\twodim{} data structure indexed by row and by column.
Such an array is a homogeneous data structure in that all the entries of
the array must belong to the same \Language{} domain (although see
\spadref{ugTypesAnyNone}).
Each array has a fixed number of rows and columns specified by the user
and arrays are not extensible.
In \Language{}, the indexing of two-dimensional arrays is one-based.
This means that both the ``first'' row of an array and the ``first''
column of an array are given the index \spad{1}.
Thus, the entry in the upper left corner of an array is in position
\spad{(1,1)}.

% It would be nice to be able to create an array from a list of rows.
% m : MATRIX INT := matrix [[1,2],[3,4]]
% is OK, but we can't do
% arr : ARRAY2 INT := array [[1,2],[3,4]]

The operation \spadfunFrom{new}{TwoDimensionalArray} creates
an array with a specified number of rows and columns and fills the components
of that array with a specified entry.
The arguments of this operation specify the number of rows, the number
of columns, and the entry.
\xtc{
This creates a five-by-four array of integers, all of whose entries are
zero.
}{
\spadcommand{arr : ARRAY2 INT := new(5,4,0) \bound{arr}}
}
The entries of this array can be set to other integers using
the operation \spadfunFromX{setelt}{TwoDimensionalArray}.

\xtc{
Issue this to set the element in the upper left corner of this array to
\spad{17}.
}{
\spadcommand{setelt!(arr, 1, 1, 17) \free{arr}\bound{arr1}}
}
\xtc{
Now the first element of the array is \spad{17.}
}{
\spadcommand{arr \free{arr1}}
}
\xtc{
Likewise, elements of an array are extracted using the operation
\spadfunFrom{elt}{TwoDimensionalArray}.
}{
\spadcommand{elt(arr,1,1) \free{arr1}}
}
\xtc{
Another way to use these two operations is as follows.
This sets the element in position \spad{(3,2)} of the array to \spad{15}.
}{
\spadcommand{arr(3,2) := 15 \free{arr1}\bound{arr2}}
}
\xtc{
This extracts the element in position \spad{(3,2)} of the array.
}{
\spadcommand{arr(3,2) \free{arr2}}
}
The operations \spadfunFrom{elt}{TwoDimensionalArray} and
\spadfunFromX{setelt}{TwoDimensionalArray} come equipped with an error
check which verifies that the indices are in the proper ranges.
For example, the above array has five rows and four columns, so if you ask
for the entry in position \spad{(6,2)} with \spad{arr(6,2)} \Language{}
displays an error message.
If there is no need for an error check, you can call the operations
\spadfunFrom{qelt}{TwoDimensionalArray} and
\spadfunFromX{qsetelt}{TwoDimensionalArray} which provide the same
functionality but without the error check.
Typically, these operations are called in well-tested programs.

\xtc{
The operations \spadfunFrom{row}{TwoDimensionalArray} and
\spadfunFrom{column}{TwoDimensionalArray} extract rows and columns,
respectively, and return objects of \spadtype{OneDimensionalArray} with
the same underlying element type.
}{
\spadcommand{row(arr,1) \free{arr2}}
}
\xtc{
}{
\spadcommand{column(arr,1) \free{arr2}}
}

\xtc{
You can determine the dimensions of an array by calling the
operations \spadfunFrom{nrows}{TwoDimensionalArray} and
\spadfunFrom{ncols}{TwoDimensionalArray},
which return the number of rows and columns, respectively.
}{
\spadcommand{nrows(arr) \free{arr2}}
}
\xtc{
}{
\spadcommand{ncols(arr) \free{arr2}}
}
\xtc{
To apply an operation to every element of an array, use
\spadfunFrom{map}{TwoDimensionalArray}.
This creates a new array.
This expression negates every element.
}{
\spadcommand{map(-,arr) \free{arr2}}
}
\xtc{
This creates an array where all the elements are doubled.
}{
\spadcommand{map((x +-> x + x),arr) \free{arr2}}
}
\xtc{
To change the array destructively, use
\spadfunFromX{map}{TwoDimensionalArray} instead of
\spadfunFrom{map}{TwoDimensionalArray}.
If you need to make a copy of any array, use
\spadfunFrom{copy}{TwoDimensionalArray}.
}{
\spadcommand{arrc := copy(arr) \bound{arrc}\free{arr2}}
}
\xtc{
}{
\spadcommand{map!(-,arrc) \free{arrc}}
}
\xtc{
}{
\spadcommand{arrc \free{arrc}}
}
\xtc{
}{
\spadcommand{arr  \free{arr2}}
}

\xtc{
Use \spadfunFrom{member?}{TwoDimensionalArray} to see if a given element
is in an array.
}{
\spadcommand{member?(17,arr) \free{arr2}}
}
\xtc{
}{
\spadcommand{member?(10317,arr) \free{arr2}}
}
\xtc{
To see how many times an element appears in an array, use
\spadfunFrom{count}{TwoDimensionalArray}.
}{
\spadcommand{count(17,arr) \free{arr2}}
}
\xtc{
}{
\spadcommand{count(0,arr) \free{arr2}}
}

For more information about the operations available for
\spadtype{TwoDimensionalArray}, issue \spadsys{)show TwoDimensionalArray}.
For information on related topics, see \xmpref{Matrix} and
\xmpref{OneDimensionalArray}.
