
% 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 domain \spadtype{Multiset(R)} is similar to \spadtype{Set(R)}
except that multiplicities
(counts of duplications) are maintained and displayed.
Use the operation \spadfunFrom{multiset}{Multiset} to create
\index{set!vs. multiset}
multisets from lists.
\index{multiset}
All the standard operations from sets are available for
multisets.
An element with multiplicity greater than one has the
multiplicity displayed first, then a colon, and then the element.

\xtc{
Create a multiset of integers.
}{
\spadcommand{s := multiset [1,2,3,4,5,4,3,2,3,4,5,6,7,4,10]\bound{s}}
}
\xtc{
The operation \spadfunX{insert} adds an element to a multiset.
}{
\spadcommand{insert!(3,s)\bound{s1}\free{s}}
}
\xtc{
Use \spadfunX{remove} to remove an element.
If a third argument is present, it specifies how many instances
to remove. Otherwise all instances of the element are removed.
Display the resulting multiset.
}{
\spadcommand{remove!(3,s,1); s\bound{s2}\free{s1}}
}
\xtc{
}{
\spadcommand{remove!(5,s); s\bound{s2}\free{s1}}
}
\xtc{
The operation \spadfun{count} returns the number of copies
of a given value.
}{
\spadcommand{count(5,s)\free{s2}}
}
\xtc{
A second multiset.
}{
\spadcommand{t := multiset [2,2,2,-9]\bound{t}}
}
\xtc{
The \spadfun{union} of two multisets is additive.
}{
\spadcommand{U := union(s,t)\bound{U}}
}
\xtc{
The \spadfun{intersect} operation gives the elements that are in
common, with additive multiplicity.
}{
\spadcommand{I := intersect(s,t)\bound{I}}
}
\xtc{
The \spadfun{difference} of \spad{s} and \spad{t} consists of
the elements that \spad{s} has but \spad{t} does not.
Elements are regarded as indistinguishable, so that if \spad{s}
and \spad{t} have any element in common, the \spadfun{difference}
does not contain that element.
}{
\spadcommand{difference(s,t)\free{s2 t}}
}
\xtc{
The \spadfun{symmetricDifference} is the \spadfun{union}
of \spad{difference(s, t)} and \spad{difference(t, s)}.
}{
\spadcommand{S := symmetricDifference(s,t)\bound{S}\free{s2 t}}
}
\xtc{
Check that the \spadfun{union} of the \spadfun{symmetricDifference} and
the \spadfun{intersect} equals the \spadfun{union} of the elements.
}{
\spadcommand{(U = union(S,I))@Boolean\free{S I U}}
}
\xtc{
Check some inclusion relations.
}{
\spadcommand{t1 := multiset [1,2,2,3]; [t1 < t, t1 < s, t < s, t1 <= s]\free{t s2}}
}
