Merge pull request #940 from zostay/cross

Fix #382: Add docs for cross and X

Author: jonathanstowe

doc/Type/List.pod6

@@ -895,11 +895,39 @@ Combining multiple cycles and C<:partial> also works:
 
 See L<this blog post for more elaboration on rotor|http://perl6.party/post/Perl-6-.rotor-The-King-of-List-Manipulation>.
 
+=head2 routine cross
+
+    sub cross(+@e, :&with) returns Seq:D
+
+Computes the cross-product of two or more lists or L<iterables|/type/Iterable>.
+This returns a sequence of lists where the first item in each list is an item
+from the first iterable, the second is from the second given iterable, etc.
+Every item will be paired with every other item in all the other lists.
+
+    say cross(<a b c>, <d e f>).map(*.join).join(",")
+    # ad,ae,af,bd,be,bf,cd,ce,cf
+
+The C<cross> routine has an infix synonym as well, named C<X>.
+
+    say (<a b c> X <d e f>).map(*.join).join(",")
+    # output is the same as the previous example
+
+If the optional C<with> parameter is passed, it is used as a reduction operation
+to apply to each of the cross product items.
+
+    say cross([1, 2, 3], [4, 5, 6], :with(&infix:<*>)).join(",");
+    # 4,5,6,8,10,12,12,15,18
+
+The C<X> operator can be combined with another operator as a meta-operator to perform a reduction as well:
+
+    say ([1, 2, 3] X* [4, 5, 6]).join(",")
+    # same output as the previous example
+
 =head2 routine zip
 
 Defined as:
 
-    sub zip(**@e) returns Seq:D
+    sub zip(+@e, :&with) returns Seq:D
 
 Zips two or more lists or other L<iterables|/type/Iterable> together by
 returning a sequence made of a list of all first elements of all lists, then a
@@ -914,6 +942,19 @@ C<zip> has an infix synonym, the C<Z> operator.
 
     say .join for <a b c> Z <d e f>;    # same output as above
 
+The optional C<with> parameter may be used to reduce the zipped lists. For
+example, the following multiplies each pair to get a result.
+
+    .say for zip (1, 2, 3), (4, 5, 6), :with(&infix:<*>);
+    # 4
+    # 10
+    # 18
+
+The C<Z> form can also be used to perform reduction like the C<with> parameter
+by using it as a meta-operator with the reducing operator:
+
+    .say for (1, 2, 3) Z* (4, 5, 6);    # same output as previous
+
 When the first input list is exhausted, no more elements are returned; so
 trailing elements from longer input lists are discarded.