=begin pod

=TITLE role Setty

=SUBTITLE Collection of distinct objects

    class Setty does QuantHash { }

A role for collections which make sure that each element can only appear once.
See L<Set> and L<SetHash>.

=head1 Methods

=head2 method grab

    method grab($count = 1)

Removes and returns C<$count> elements chosen at random (without repetition)
from the set.

If C<*> is passed as C<$count>, or C<$count> is greater than or equal to the
size of the set, then all its elements are removed and returned in random order.

Only works on mutable sets; When used on an immutable set, it results in an
exception.

=head2 method grabpairs

    method grabpairs($count = 1)

Removes C<$count> elements chosen at random (without repetition) from the set,
and returns a list of C<Pair> objects whose keys are the grabbed elements and
whose values are C<True>.

If C<*> is passed as C<$count>, or C<$count> is greater than or equal to the
size of the set, then all its elements are removed and returned as C<Pair>s in
the aforementioned way in random order.

Only works on mutable sets; When used on an immutable set, it results in an
exception.

=head2 method pick

    multi method pick($count = 1)

Returns C<$count> elements chosen at random (without repetition) from the set.

If C<*> is passed as C<$count>, or C<$count> is greater than or equal to the
size of the set, then all its elements are returned in random order.

=head2 method roll

    multi method roll($count = 1)

Returns a lazy list of C<$count> elements, each randomly selected from the set.
Each random choice is made independently, like a separate die roll where each
die face is a set element.

If C<*> is passed as C<$count>, the list is infinite.

=head2 method keys

Returns a list of all elements of the set.

=head2 method values

Returns a list containing as many C<True> values as the set has elements.

=head2 method kv

Returns a list of the set's elements and C<True> values interleaved.

=head2 method elems

    method elems(--> Int)

The number of elements of the set.

=head2 method total

    method total(--> Int)

The total of all the values of the C<QuantHash> object. For a C<Setty>
object, this is just the number of elements.

=head2 method ACCEPTS

    method ACCEPTS($other)

Returns C<True> if C<$other> and C<self> contain all the same elements,
and no others.

=head1 See Also

L<Sets, Bags, and Mixes|/language/setbagmix>

=end pod
