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


%
% ALIST.htex

The \spadtype{AssociationList} constructor provides a general structure for
associative storage.
\index{list!association}
This type provides association lists in which data objects can be saved
\index{association list}
according to keys of any type.
For a given association list, specific types must be chosen for the keys and
entries.
You can think of the representation of an association list as a list
of records with key and entry fields.

Association lists are a form of table and so most of the operations available
\index{table}
for \spadtype{Table} are also available for \spadtype{AssociationList}.
They can also be viewed as lists and can be manipulated accordingly.

\xtc{
This is a \pspadtype{Record} type with age and gender fields.
}{
\spadcommand{Data := Record(monthsOld : Integer, gender : String) \bound{Data}}
}
\xtc{
In this expression, \spad{al} is declared to be an association
list whose keys are strings and whose entries are the above records.
}{
\spadcommand{al : AssociationList(String,Data) \free{Data}\bound{al}}
}
\xtc{
The \spadfunFrom{table}{AssociationList} operation is used to create
an empty association list.
}{
\spadcommand{al := table() \free{al}\bound{al1}}
}
\xtc{
You can use assignment syntax to add things to the association list.
}{
\spadcommand{al."bob" := [407,"male"]\$Data \free{al1}\bound{al2}}
}
\xtc{
}{
\spadcommand{al."judith" := [366,"female"]\$Data \free{al2}\bound{al3}}
}
\xtc{
}{
\spadcommand{al."katie" := [24,"female"]\$Data \free{al3}\bound{al4}}
}
\xtc{
Perhaps we should have included a species field.
}{
\spadcommand{al."smokie" := [200,"female"]\$Data \free{al4}\bound{al5}}
}
\xtc{
Now look at what is in the association list.
Note that the last-added (key, entry) pair is at the beginning of the list.
}{
\spadcommand{al \free{al5}}
}
\xtc{
You can reset the entry for an existing key.
}{
\spadcommand{al."katie" := [23,"female"]\$Data \free{al5}\bound{al6}}
}
\xtc{
Use \spadfunFromX{delete}{AssociationList} to destructively remove
an element of the association list.
Use \spadfunFrom{delete}{AssociationList} to return a copy of the
association list with the element deleted.
The second argument is the index of the element to delete.
}{
\spadcommand{delete!(al,1) \free{al6}\bound{al7}}
}

For more information about tables, see \xmpref{Table}.
For more information about lists, see \xmpref{List}.
\showBlurb{AssociationList}
