
% 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{SparseTable} domain provides a general purpose
table type with default entries.
\xtc{
Here we create a table to save strings under integer keys.
The value \spad{"Try again!"} is returned if no other value has been
stored for a key.
}{
\spadcommand{t: SparseTable(Integer, String, "Try again!") := table() \bound{t}}
}
\xtc{
Entries can be stored in the table.
}{
\spadcommand{t.3 := "Number three" \free{t}\bound{t1}}
}
\xtc{
}{
\spadcommand{t.4 := "Number four" \free{t}\bound{t2}}
}
\xtc{
These values can be retrieved as usual, but if a look up fails
the default entry will be returned.
}{
\spadcommand{t.3 \free{t1}}
}
\xtc{
}{
\spadcommand{t.2 \free{t}}
}
\xtc{
To see which values are explicitly stored, the
\spadfunFrom{keys}{SparseTable} and \spadfunFrom{entries}{SparseTable}
functions can be used.
}{
\spadcommand{keys t \free{t1 t2}}
}
\xtc{
}{
\spadcommand{entries t \free{t1 t2}}
}
If a specific table representation
is required, the \spadtype{GeneralSparseTable} constructor should be used.
The domain \spadtype{SparseTable(K, E, dflt)} is equivalent to
\spadtype{GeneralSparseTable(K,E, Table(K,E), dflt)}.
\exptypeindex{GeneralSparseTable}
For more information, see
\xmpref{Table} and
\xmpref{GeneralSparseTable}.
\showBlurb{SparseTable}
