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

[kuhar]

Summary

Update the documentation comment and add a new test case.

Add an assertion in zip_first checking the iteratee length precondition.

[dblaikie]

llvm/include/llvm/ADT/STLExtras.h

882–886

Worth mentioning what values are used to fill in if the second iteratee isn't long enough?

[kuhar]

llvm/include/llvm/ADT/STLExtras.h

882–886

Unless I'm mistaken, that's just UB. The first sentence explains that zip_first assumes that the first iteratee is the shortest.

Do you see some better wording here?

[kuhar]

llvm/include/llvm/ADT/STLExtras.h

882–886

Actually, maybe that would deserve it's own assertion as well.

[kuhar]

Add an assertion in zip_first and a test case.

[kuhar]

Simplify assertion

[dblaikie]

llvm/include/llvm/ADT/STLExtras.h

882–886

Ah, I see, fair enough.

Sure, could add an assertion here if you like - either in this review or separate commit.

llvm/include/llvm/ADT/STLExtras.h

public:
   iterator begin() const {
     return begin_impl(std::index_sequence_for<Args...>{});
   }
   iterator end() const { return end_impl(std::index_sequence_for<Args...>{}); }
 };
 
 } // 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)...);
 }
 
 namespace detail {
 template <typename Iter>
 Iter next_or_end(const Iter &I, const Iter &End) {
   if (I == End)

llvm/unittests/ADT/IteratorTest.cpp

for (int *P : make_pointer_range(A))
     EXPECT_EQ(A + I++, P);
 }
 
 TEST(ZipIteratorTest, Basic) {
   using namespace std;
   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) {
   using namespace std;
   const SmallVector<unsigned, 6> pi{3, 1, 4, 1, 5, 9};
   unsigned iters = 0;
 
   for (auto tup : zip_first(SmallVector<bool, 0>{1, 1, 0, 1}, pi)) {
     EXPECT_EQ(get<0>(tup), get<1>(tup) & 0x01);
     iters += 1;
   }
 
   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};
   const vector<StringRef> e{"2", "7", "1", "8"};
 
   {
     // Check left range longer than right.
     const vector<tuple<Optional<unsigned>, Optional<StringRef>>> expected{