Document Bag ops

lib/Bag.pod

@@ -22,58 +22,113 @@ Creates a new C<Bag> from C<@args>.
 
     only sub infix:<(|)>(**@p)
 
+Returns the union of all of its arguments. If any of its arguments are
+C<Baggy>, it creates a new C<Bag> that contains all the elements of the
+arguments, each weighed by the highest weight that appeared for that
+element.
+
+    bag(<a a b c a>) (|) bag(<a a b c c>) == bag(<a a a b c c>)
+
 =head2 infix ∪
 
     only sub infix:<<"\x222A">>(|p)
 
+Equivalent to L«infix (V<|>)».
+
 =head2 infix (&)
 
     only sub infix:<(&)>(**@p)
 
+Returns the intersection of all its elements. If any of its arguments
+are C<Baggy>, this creates a new C<Bag> that contains only the elements
+that all of the arguments contain, each weighted the max weight all of
+the arguments share for that element.
+
+    bag(<a a b c a>) (&) bag(<a a b c c>) == bag(<a a b c>)
+
 =head2 infix ∩
 
     only sub infix:<<"\x2229">>(|p)
 
+Equivalent to L«infix (&)».
+
 =head2 infix (-)
 
     only sub infix:<(-)>(**@p)
 
+If the first argument is C<Baggy>, returns a C<Bag> that contains each
+element of the first argument with its weight subtracted by the weight
+of that element in each of the other arguments.
+
+    bag(<a a b c a d>) (-) bag(<a a b c c>) = bag(<a d>)
+
 =head2 infix ∖
 
     only sub infix:<<"\x2216">>(|p)
 
+Equivalent to L«infix (-)».
+
 =head2 infix (.)
 
     only sub infix:<(.)>(**@p)
 
+Returns a C<Bag> that contains each element of the arguments with the
+weights of the element across the arguments multiplied together to get
+the new weight.
+
+    bag(<a a b c a d>) (.) bag(<a a b c c>) == bag(<a a a a a a b c c>)
+
 =head2 infix ⊍
 
     only sub infix:<<"\x228D">>(|p)
 
+Equivalent to L«infix (.)».
+
 =head2 infix (+)
 
     only sub infix:<(+)>(**@p)
 
+Returns a C<Bag> that contains each element of the arguments with the
+weights of the element across the arguments added together to get
+the new weight.
+
+    bag(<a a b c a d>) (.) bag(<a a b c c>) == bag(<a a a a a b b c c c d>)
+
+
 =head2 infix ⊎
 
     only sub infix:<<"\x228E">>(|p)
 
+Equivalent to L«infix (+)».
+
 =head2 infix (<+)
 
     multi sub infix:<<(<+)>>(Any $a, Any $b --> Bool)
     multi sub infix:<<(<+)>>(Baggy $a, Baggy $b --> Bool)
 
+Returns C<True> if C<$a> is a baggy subset of C<$b>, i.e., if all the
+elements of C<$a> are in C<$b> and each argument of C<$a> is weighed at
+least as heavily as the element is in C<$b>.
+
 =head2 infix ≼
 
     only sub infix:<<"\x227C">>($a, $b --> Bool)
 
+Equivalent to L«infix (<+)».
+
 =head2 infix (>+)
 
     multi sub infix:<<(>+)>>(Baggy $a, Baggy $b --> Bool)
     multi sub infix:<<(>+)>>(Any $a, Any $b --> Bool)
 
+Returns C<True> if C<$a> is a baggy superset of C<$b>, i.e., if all the
+elements of C<$b> are in C<$a> and no argument of C<$a> is weighted
+heavier than that element is in C<$b>.
+
 =head2 infix ≽
 
     only sub infix:<<"\x227D">>($a, $b --> Bool)
 
+Equivalent to L«infix (+>)».
+
 =end pod

lib/Set.pod

@@ -84,7 +84,7 @@ its arguments contain.
 
     only sub infix:<<"\x222A">>(|p)
 
-Equivalent to L«#infix (|)».
+Equivalent to L«#infix (V<|>)».
 
 =head2 infix (&)