% Copyright The Numerical Algorithms Group Limited 1992-94. All rights reserved.
% !! DO NOT MODIFY THIS FILE BY HAND !! Created by ht.awk.
\newcommand{\TableXmpTitle}{Table}
\newcommand{\TableXmpNumber}{9.80}
%
% =====================================================================
\begin{page}{TableXmpPage}{9.80 Table}
% =====================================================================
\beginscroll
%

The \spadtype{Table} constructor provides a general structure
for associative storage.
This type provides hash tables in which data objects
can be saved according to keys of any type.
For a given table, specific types must be chosen for the keys and entries.

\xtc{
In this example the keys to the table are polynomials with
integer coefficients.
The entries in the table are strings.
}{
\spadpaste{t: Table(Polynomial Integer, String) := table() \bound{t}}
}
\xtc{
To save an entry in the table, the \spadfunFrom{setelt}{Table} operation is used.
This can be called directly, giving the table a key and an entry.
}{
\spadpaste{setelt(t, x**2 - 1, "Easy to factor") \bound{p1}\free{t}}
}
\xtc{
Alternatively, you can use assignment syntax.
}{
\spadpaste{t(x**3 + 1) := "Harder to factor" \bound{p2}\free{p1}}
}
\xtc{
}{
\spadpaste{t(x)        := "The easiest to factor" \bound{p3}\free{p2}}
}
\xtc{
Entries are retrieved from the table by calling the
\spadfunFrom{elt}{Table} operation.
}{
\spadpaste{elt(t, x) \free{p3}}
}
\xtc{
This operation is called when a table is ``applied'' to a key using
this or the following syntax.
}{
\spadpaste{t.x \free{p3}}
}
\xtc{
}{
\spadpaste{t x \free{p3}}
}
\xtc{
Parentheses are used only for grouping.  They are needed if the key is
an infixed expression.
}{
\spadpaste{t.(x**2 - 1) \free{p3}}
}
\xtc{
Note that the \spadfunFrom{elt}{Table} operation is used only when the
key is known to be in the table---otherwise an error is generated.
}{
\spadpaste{t (x**3 + 1) \free{p3}}
}

\xtc{
You can get a list of all the keys to a table using the
\spadfunFrom{keys}{Table} operation.
}{
\spadpaste{keys t \free{p3}}
}
\xtc{
If you wish to test whether a key is in a table, the
\spadfunFrom{search}{Table} operation is used.
This operation returns either an entry or \spad{"failed"}.
}{
\spadpaste{search(x, t) \free{p3}}
}
\xtc{
}{
\spadpaste{search(x**2, t) \free{p3}}
}
\xtc{
The return type is a union so the success of the search can be tested
using \spad{case}.
\spadkey{case}
}{
\spadpaste{search(x**2, t) case "failed" \free{p3}}
}
\xtc{
The \spadfunFromX{remove}{Table} operation is used to delete values from a
table.
}{
\spadpaste{remove!(x**2-1, t) \free{p3} \bound{p4}}
}
\xtc{
If an entry exists under the key, then it is returned.  Otherwise
\spadfunFromX{remove}{Table} returns \spad{"failed"}.
}{
\spadpaste{remove!(x-1, t) \free{p4}\bound{p5}}
}

\xtc{
The number of key-entry pairs can be found using the
\spadfunFrom{\#}{Table} operation.
}{
\spadpaste{\#t \free{p5}}
}
\xtc{
Just as \spadfunFrom{keys}{Table} returns a list of keys to the table, a
list of all the entries can be obtained using the
\spadfunFrom{members}{Table} operation.
}{
\spadpaste{members t \free{p5}}
}
\xtc{
A number of useful operations take functions and map them on to the
table to compute the result.  Here we count the entries which
have \spad{"Hard"} as a prefix.
}{
\spadpaste{count(s: String +-> prefix?("Hard", s), t) \free{p5}}
}

Other table types are provided to support various needs.
\indent{4}
\beginitems
\item[-] \spadtype{AssociationList} gives a list with a table view.
This allows new entries to be appended onto the front of the list
to cover up old entries.
This is useful when table entries need to be stacked or when
frequent list traversals are required.
See \downlink{`AssociationList'}{AssociationListXmpPage}\ignore{AssociationList} for more information.
\item[-] \spadtype{EqTable} gives tables in which keys are considered
equal only when they are in fact the same instance of a structure.
See \downlink{`EqTable'}{EqTableXmpPage}\ignore{EqTable} for more information.
\item[-] \spadtype{StringTable} should be used when the keys are known to
be strings.
See \downlink{`StringTable'}{StringTableXmpPage}\ignore{StringTable} for more information.
\item[-] \spadtype{SparseTable} provides tables with default
entries, so
lookup never fails.  The \spadtype{GeneralSparseTable} constructor
can be used to make any table type behave this way.
See \downlink{`SparseTable'}{SparseTableXmpPage}\ignore{SparseTable} for more information.
\item[-] \spadtype{KeyedAccessFile} allows values to be saved in a file,
accessed as a table.
See \downlink{`KeyedAccessFile'}{KeyedAccessFileXmpPage}\ignore{KeyedAccessFile} for more information.
\enditems
\indent{0}
%
\showBlurb{Table}
\endscroll
\autobuttons
\end{page}
%