[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–884

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–884

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–884

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–884

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.
 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) {
   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)) {