Merge pull request #63 from edwinst/master

Emphasize unorderedness of "Sets, Bags, and Mixes".

lib/Language/setbagmix.pod

@@ -2,22 +2,33 @@
 
 =TITLE Sets, Bags, and Mixes
 
-=SUBTITLE Unique collections and weighted lists in Perl 6
-
-Often, one wants to work with lists of values that are unique. While calling
-L<C<.unique>|unique> on the list repeatedly is certainly an option, better
-still is to use a L<B<C<Set>>|Set> or L<B<C<SetHash>>|SetHash>, whose
-elements are guaranteed to be unique.
+=SUBTITLE Unordered collections of unique and weighted objects in Perl 6
+
+Often you want to collect objects in a container but you do not care
+about the order of these objects. For such cases, Perl 6 provides the
+I<unordered> collection types L<B<C<Set>>|Set>,
+L<B<C<SetHash>>|SetHash>, L<B<C<Bag>>|Bag>, L<B<C<BagHash>>|BagHash>,
+L<B<C<Mix>>|Mix>, and L<B<C<MixHash>>|MixHash>. Being unordered, these
+containers can be more efficient than L<B<C<Lists>>|List> for looking up
+elements or dealing with repeated items.
+
+If you want to get the contained objects (elements) without duplicates
+and you only care I<whether> an element is in the collection or not,
+you can use a L<B<C<Set>>|Set> or L<B<C<SetHash>>|SetHash>. (If you want
+to get rid of duplicates but still preserve order, take a look at the
+L<C<unique>|unique> routine for L<B<C<Lists>>|List>.)
 
 =begin comment
 =defn  Set or SetHash
 Collection of distinct objects
 =end comment
 
-Other times, one wants to keep track of the number of occurrences of an
-item. One could use a hash E<emdash> or use the built-in L<B<C<Bag>>|Bag> or
-L<B<C<BagHash>>|BagHash> types (for integer numbers) or the L<B<C<Mix>>|Mix>
-or L<B<C<MixHash>>|MixHash> types (for arbitrary numbers).
+If you want to keep track of the number of times each object appeared,
+you can use a L<B<C<Bag>>|Bag> or L<B<C<BagHash>>|BagHash>. In these
+Baggy containers each element has a weight (an unsigned integer)
+indicating the number of times the same object has been included in the
+collection. The types L<B<C<Mix>>|Mix> and L<B<C<MixHash>>|MixHash> are
+similar, but they also allow fractional weights.
 
 =begin comment
 =defn  Bag or BagHash
@@ -31,6 +42,11 @@ Collection of distinct objects mapped to real-number weights
 TODO: Partial type graph showing only QuantHash, Setty, Baggy, Mixy, Set,
       SetHash, Bag, BagHash, Mix, MixHash.
 
+L<B<C<Set>>|Set>, L<B<C<Bag>>|Bag>, and L<B<C<Mix>>|Mix> are I<immutable>
+types. Use the mutable variants L<B<C<SetHash>>|SetHash>, L<B<C<BagHash>>|BagHash>,
+and L<B<C<MixHash>>|MixHash> if you want to add or remove elements after
+the container has been constructed.
+
 The six collection classes C<Set>, C<SetHash>, C<Bag>, C<BagHash>, C<Mix>,
 C<MixHash>, all share similar semantics.