[ADT] Clarify `zip` behavior with iteratees of different lengths

Update the documentation comment and add a new test case.

Add an assertion in `zip_first` checking the iteratee length precondition.

Reviewed By: dblaikie

Differential Revision: https://reviews.llvm.org/D138858

llvm/include/llvm/ADT/STLExtras.h

@@ -870,19 +870,27 @@ public:
 
 } // end namespace detail
 
-/// zip iterator for two or more iteratable types.
+/// zip iterator for two or more iteratable types. Iteration continues until the
+/// end of the *shortest* iteratee is reached.
 template <typename T, typename U, typename... Args>
 detail::zippy<detail::zip_shortest, T, U, Args...> zip(T &&t, U &&u,
-                                                       Args &&... args) {
+                                                       Args &&...args) {
   return detail::zippy<detail::zip_shortest, T, U, Args...>(
       std::forward<T>(t), std::forward<U>(u), std::forward<Args>(args)...);
 }
 
 /// zip iterator that, for the sake of efficiency, assumes the first iteratee to
-/// be the shortest.
+/// be the shortest. Iteration continues until the end of the first iteratee is
+/// reached. In builds with assertions on, we check that the assumption about
+/// the first iteratee being the shortest holds.
 template <typename T, typename U, typename... Args>
 detail::zippy<detail::zip_first, T, U, Args...> zip_first(T &&t, U &&u,
-                                                          Args &&... args) {
+                                                          Args &&...args) {
+  assert(std::distance(adl_begin(t), adl_end(t)) <=
+             std::min({std::distance(adl_begin(u), adl_end(u)),
+                       std::distance(adl_begin(args), adl_end(args))...}) &&
+         "First iteratee is not the shortest");
+
   return detail::zippy<detail::zip_first, T, U, Args...>(
       std::forward<T>(t), std::forward<U>(u), std::forward<Args>(args)...);
 }

llvm/unittests/ADT/IteratorTest.cpp

@@ -395,16 +395,25 @@ TEST(ZipIteratorTest, Basic) {
   const SmallVector<unsigned, 6> pi{3, 1, 4, 1, 5, 9};
   SmallVector<bool, 6> odd{1, 1, 0, 1, 1, 1};
   const char message[] = "yynyyy\0";
+  std::array<int, 2> shortArr = {42, 43};
 
   for (auto tup : zip(pi, odd, message)) {
     EXPECT_EQ(get<0>(tup) & 0x01, get<1>(tup));
     EXPECT_EQ(get<0>(tup) & 0x01 ? 'y' : 'n', get<2>(tup));
   }
 
-  // note the rvalue
+  // Note the rvalue.
   for (auto tup : zip(pi, SmallVector<bool, 0>{1, 1, 0, 1, 1})) {
     EXPECT_EQ(get<0>(tup) & 0x01, get<1>(tup));
   }
+
+  // Iterate until we run out elements in the *shortest* range.
+  for (auto [idx, elem] : enumerate(zip(odd, shortArr))) {
+    EXPECT_LT(idx, static_cast<size_t>(2));
+  }
+  for (auto [idx, elem] : enumerate(zip(shortArr, odd))) {
+    EXPECT_LT(idx, static_cast<size_t>(2));
+  }
 }
 
 TEST(ZipIteratorTest, ZipFirstBasic) {
@@ -420,6 +429,21 @@ TEST(ZipIteratorTest, ZipFirstBasic) {
   EXPECT_EQ(iters, 4u);
 }
 
+#if !defined(NDEBUG) && GTEST_HAS_DEATH_TEST
+// Make sure that we can detect when the first range is not the shortest.
+TEST(ZipIteratorTest, ZipFirstNotShortest) {
+  const std::array<unsigned, 6> longer = {};
+  const std::array<unsigned, 4> shorter = {};
+
+  EXPECT_DEATH(zip_first(longer, shorter),
+               "First iteratee is not the shortest");
+  EXPECT_DEATH(zip_first(longer, shorter, longer),
+               "First iteratee is not the shortest");
+  EXPECT_DEATH(zip_first(longer, longer, shorter),
+               "First iteratee is not the shortest");
+}
+#endif
+
 TEST(ZipIteratorTest, ZipLongestBasic) {
   using namespace std;
   const vector<unsigned> pi{3, 1, 4, 1, 5, 9};