From 74d13d0ccd8e5c19d45a3b48f9908934356c84d8 Mon Sep 17 00:00:00 2001
From: "Paul \"LeoNerd\" Evans" <leonerd@leonerd.org.uk>
Date: Tue, 30 Mar 2021 17:51:18 +0100
Subject: [PATCH] =?UTF-8?q?Better=20upfront=20docs=20about=20zip/mesh's=20?=
 =?UTF-8?q?handling=20of=20gaps=20in=20input;=20further=20docs=20re=C3=A4r?=
 =?UTF-8?q?rangement=20about=20the=20=5Fshortest=20/=20=5Flongest=20varian?=
 =?UTF-8?q?ts?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 lib/List/Util.pm | 26 ++++++++++++++++----------
 1 file changed, 16 insertions(+), 10 deletions(-)

diff --git a/lib/List/Util.pm b/lib/List/Util.pm
index e8e020b..ae8a658 100644
--- a/lib/List/Util.pm
+++ b/lib/List/Util.pm
@@ -662,7 +662,9 @@ I<Since version TODO.>
 
 Returns a list of array references, composed of elements from the given list
 of array references. Each array in the returned list is composed of elements
-at that corresponding position from each of the given input arrays.
+at that corresponding position from each of the given input arrays. If any
+input arrays run out of elements before others, then C<undef> will be inserted
+into the result to fill in the gaps.
 
 The C<zip> function is particularly handy for iterating over multiple arrays
 at the same time with a C<foreach> loop, taking one element from each:
@@ -680,16 +682,17 @@ so make sure to invoke it with references to arrays.
 For a function similar to the C<zip> function from C<List::MoreUtils>, see
 L<mesh>.
 
-    my @result = zip_longest ...
     my @result = zip_shortest ...
 
-These different variations of the function differ in how they behave when
-given input arrays of differing lengths. C<zip_longest> will continue while
-any of the inputs still have elements, inserting C<undef> into the result if
-some input arrays have already run out. C<zip_shortest> will stop as soon as
-the shortest input runs out of elements, discarding any unused ones.
+A variation of the function that differs in how it behaves when given input
+arrays of differing lengths. C<zip_shortest> will stop as soon as any one of
+the input arrays run out of elements, discarding any remaining unused values
+from the others.
+
+    my @result = zip_longest ...
 
-The plain C<zip> function is an alias to C<zip_longest>.
+C<zip_longest> is an alias to the C<zip> function, provided simply to be
+explicit about that behaviour as compared to C<zip_shortest>.
 
 =head2 mesh
 
@@ -700,7 +703,9 @@ I<Since version TODO.>
 
 Returns a list of items collected from elements of the given list of array
 references. Each section of items in the returned list is composed of elements
-at the corresponding position from each of the given input arrays.
+at the corresponding position from each of the given input arrays. If any
+input arrays run out of elements before others, then C<undef> will be inserted
+into the result to fill in the gaps.
 
 This is similar to L<zip>, except that all of the ranges in the result are
 returned in one long flattened list, instead of being bundled into separate
@@ -718,9 +723,10 @@ equivalent to C<List::MoreUtils::mesh> or C<List::MoreUtils::zip> (themselves
 aliases of each other). This function does not apply a prototype, so make sure
 to invoke it with references to arrays.
 
-    my @result = mesh_longest ...
     my @result = mesh_shortest ...
 
+    my @result = mesh_longest ...
+
 These variations are similar to those of L<zip>, in that they differ in
 behaviour when one of the input lists runs out of elements before the others.