Merge pull request #2358 from Coleoid/mixhash-todo

Document the Setty ops for MixHashes per TODO

Author: JJ

doc/Language/setbagmix.pod6

@@ -31,7 +31,7 @@ collection.
 
 The types L<Mix|/type/Mix> and L<MixHash|/type/MixHash> are similar
 to L<Bag|/type/Bag> and L<BagHash|/type/BagHash>, but they also
-allow B<fractional weights>.
+allow B<fractional and negative weights>.
 
 =begin comment
 =defn  Bag or BagHash

doc/Type/BagHash.pod6

@@ -86,22 +86,36 @@ my ($a, $b) = BagHash.new(2, 2, 4), BagHash.new(2, 3, 3, 4);
 
 say $a (<) $b;   # OUTPUT: «False␤»
 say $a (<+) $b;  # OUTPUT: «False␤»
-say $a (^) $b;   # OUTPUT: «bag(3(2), 2)␤»
-say $a (+) $b;   # OUTPUT: «bag(2(3), 4(2), 3(2))␤»
+say $a (^) $b;   # OUTPUT: «Bag(3(2), 2)␤»
+say $a (+) $b;   # OUTPUT: «Bag(2(3), 4(2), 3(2))␤»
 
 # Unicode versions:
 say $a ⊂ $b;  # OUTPUT: «False␤»
 say $a ≼ $b;  # OUTPUT: «False␤»
-say $a ⊖ $b;  # OUTPUT: «bag(3(2), 2)␤»
-say $a ⊎ $b;  # OUTPUT: «bag(2(3), 4(2), 3(2))␤»
+say $a ⊖ $b;  # OUTPUT: «Bag(3(2), 2)␤»
+say $a ⊎ $b;  # OUTPUT: «Bag(2(3), 4(2), 3(2))␤»
 =end code
 
 See L<Set/Bag Operators|/language/setbagmix#Set/Bag_operators> for a complete list of
 set and bag operators with detailed explanations.
 
 =head1 Note on C<reverse> and ordering.
 
-This method is inherited from L<Any|/type/Any#routine_reverse>, however, C<Mix>es do not have an inherent order and you should not trust it returning a consistent output.
+BagHash inherits C<reverse> from L<Any|/type/Any#routine_reverse>,
+however, C<Bag>s do not have an inherent order and you should not trust
+it returning a consistent output.
+
+If you sort a BagHash, the result is a list of pairs, at which point
+C<reverse> makes perfect sense:
+
+=begin code
+my $a = BagHash.new(2, 2, 18, 3, 4);
+say $a;  # OUTPUT: «BagHash(18, 2(2), 3, 4)␤»
+
+say $a.sort;  # OUTPUT: «(2 => 2 3 => 1 4 => 1 18 => 1)␤»
+say $a.sort.reverse;  # OUTPUT: «(18 => 1 4 => 1 3 => 1 2 => 2)␤»
+=end code
+
 
 =head1 See Also
 

doc/Type/MixHash.pod6

@@ -68,16 +68,42 @@ the mix, and the (cumulative) values become the associated numeric weights:
 
 =head1 Operators
 
-=begin comment
 
-TODO: Expand this section (using the corresponding section in
-lib/Type/BagHash.pod as a guide) after ab5tract's set/bag/mix operator redesign.
-
-=end comment
+=begin code
+my ($a, $b) = MixHash(2 => 2, 4), MixHash(2 => 1.5, 3 => 2, 4);
+
+say $a (<) $b;   # OUTPUT: «False␤»
+say $a (<+) $b;  # OUTPUT: «False␤»
+say $a (^) $b;   # OUTPUT: «Mix(2(0.5), 3(2))␤»
+say $a (+) $b;   # OUTPUT: «Mix(2(3.5), 4(2), 3(2))␤»
+
+# Unicode versions:
+say $a ⊂ $b;  # OUTPUT: «False␤»
+say $a ≼ $b;  # OUTPUT: «False␤»
+say $a ⊖ $b;  # OUTPUT: «Mix(2(0.5), 3(2))␤»
+say $a ⊎ $b;  # OUTPUT: «Mix(2(3.5), 4(2), 3(2))␤»
+=end code
 
 See L<Set/Bag Operators|/language/setbagmix#Set/Bag_operators> for a complete list of set and bag operators
 with detailed explanations.
 
+=head1 Note on C<reverse> and ordering.
+
+MixHash inherits C<reverse> from L<Any|/type/Any#routine_reverse>,
+however, C<Mix>es do not have an inherent order and you should not trust
+it returning a consistent output.
+
+If you sort a MixHash, the result is a list of pairs, at which point
+C<reverse> makes perfect sense:
+
+=begin code
+my $a = MixHash.new(2, 2, 18, 3, 4);
+say $a;  # OUTPUT: «MixHash(18, 2(2), 3, 4)␤»
+
+say $a.sort;  # OUTPUT: «(2 => 2 3 => 1 4 => 1 18 => 1)␤»
+say $a.sort.reverse;  # OUTPUT: «(18 => 1 4 => 1 3 => 1 2 => 2)␤»
+=end code
+
 =head1 Methods
 
 =head2 method Bag
@@ -86,7 +112,8 @@ Defined as:
 
     method Bag (--> Bag:D)
 
-Coerces the C<MixHash> to a L«C<Bag>|/type/Bag». The weights are convert to L«C<Int>|/type/Int»,
+Coerces the C<MixHash> to a L«C<Bag>|/type/Bag». The weights are converted
+to L«C<Int>|/type/Int»,
 which means the number of keys in the resulting C<Bag> can be fewer than in the
 original C<MixHash>, if any of the weights are negative or truncate to zero.
 
@@ -96,13 +123,16 @@ Defined as:
 
     method BagHash (--> BagHash:D)
 
-Coerces the C<MixHash> to a L«C<BagHash>|/type/BagHash». The weights are convert to L«C<Int>|/type/Int»,
+Coerces the C<MixHash> to a L«C<BagHash>|/type/BagHash». The weights are converted
+to L«C<Int>|/type/Int»,
 which means the number of keys in the resulting C<BagHash> can be fewer than in the
 original C<MixHash>, if any of the weights are negative or truncate to zero.
 
 =head1 Note on C<reverse> and ordering
 
-This method is inherited from L<Any|/type/Any#routine_reverse>, however, C<Mix>es do not have an inherent order and you should not trust it returning a consistent output.
+This method is inherited from L<Any|/type/Any#routine_reverse>, however,
+C<Mix>es do not have an inherent order and you should not trust it returning
+a consistent output.
 
 =head1 See Also