[libcxx][iterator] adds `std::ranges::advance`

Implements part of P0896 'The One Ranges Proposal'.
Implements [range.iter.op.advance].

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

libcxx/include/CMakeLists.txt

@@ -7,10 +7,12 @@ set(files
   __config
   __debug
   __errc
+  __function_like.h
   __functional_03
   __functional_base
   __functional_base_03
   __hash_table
+  __iterator/advance.h
   __iterator/concepts.h
   __iterator/incrementable_traits.h
   __iterator/iter_move.h

libcxx/include/__function_like.h

@@ -0,0 +1,56 @@
+// -*- C++ -*-
+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef _LIBCPP___ITERATOR_FUNCTION_LIKE_H
+#define _LIBCPP___ITERATOR_FUNCTION_LIKE_H
+
+#include <__config>
+
+#if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
+#pragma GCC system_header
+#endif
+
+_LIBCPP_PUSH_MACROS
+#include <__undef_macros>
+
+_LIBCPP_BEGIN_NAMESPACE_STD
+
+#if !defined(_LIBCPP_HAS_NO_RANGES)
+
+namespace ranges {
+// Per [range.iter.ops.general] and [algorithms.requirements], functions in namespace std::ranges
+// can't be found by ADL and inhibit ADL when found by unqualified lookup. The easiest way to
+// facilitate this is to use function objects.
+//
+// Since these are still standard library functions, we use `__function_like` to eliminate most of
+// the properties that function objects get by default (e.g. semiregularity, addressability), to
+// limit the surface area of the unintended public interface, so as to curb the effect of Hyrum's
+// law.
+struct __function_like {
+  __function_like() = delete;
+  __function_like(__function_like const&) = delete;
+  __function_like& operator=(__function_like const&) = delete;
+
+  void operator&() const = delete;
+
+  struct __tag { };
+
+protected:
+  constexpr explicit __function_like(__tag) noexcept {}
+  ~__function_like() = default;
+};
+} // namespace ranges
+
+#endif // !defined(_LIBCPP_HAS_NO_RANGES)
+
+_LIBCPP_END_NAMESPACE_STD
+
+_LIBCPP_POP_MACROS
+
+#endif // _LIBCPP___ITERATOR_FUNCTION_LIKE_H

libcxx/include/__iterator/advance.h

@@ -0,0 +1,157 @@
+// -*- C++ -*-
+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef _LIBCPP___ITERATOR_ADVANCE_H
+#define _LIBCPP___ITERATOR_ADVANCE_H
+
+#include <__config>
+#include <__debug>
+#include <__function_like.h>
+#include <__iterator/concepts.h>
+#include <__iterator/incrementable_traits.h>
+#include <concepts>
+#include <limits>
+#include <type_traits>
+#include <utility>
+
+#if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
+#pragma GCC system_header
+#endif
+
+_LIBCPP_PUSH_MACROS
+#include <__undef_macros>
+
+_LIBCPP_BEGIN_NAMESPACE_STD
+
+#if !defined(_LIBCPP_HAS_NO_RANGES)
+
+namespace ranges {
+// [range.iter.op.advance]
+struct __advance_fn final : __function_like {
+private:
+  template <signed_integral _Tp>
+  static constexpr make_unsigned_t<_Tp> __abs(_Tp const __n) noexcept {
+    auto const __unsigned_n = __to_unsigned_like(__n);
+    auto const __complement = ~__unsigned_n + 1;
+    return __n < 0 ? __complement : __unsigned_n;
+  }
+
+  template <class _Ip>
+  static constexpr void __advance_forward(_Ip& __i, iter_difference_t<_Ip> __n) {
+    while (__n > 0) {
+      --__n;
+      ++__i;
+    }
+  }
+
+  template <class _Ip>
+  static constexpr void __advance_backward(_Ip& __i, iter_difference_t<_Ip> __n) {
+    while (__n < 0) {
+      ++__n;
+      --__i;
+    }
+  }
+
+public:
+  constexpr explicit __advance_fn(__tag __x) noexcept : __function_like(__x) {}
+
+  // Preconditions: If `I` does not model `bidirectional_iterator`, `n` is not negative.
+  template <input_or_output_iterator _Ip>
+  constexpr void operator()(_Ip& __i, iter_difference_t<_Ip> __n) const {
+    _LIBCPP_ASSERT(__n >= 0 || bidirectional_iterator<_Ip>,
+                   "If `n < 0`, then `bidirectional_iterator<I>` must be true.");
+
+    // If `I` models `random_access_iterator`, equivalent to `i += n`.
+    if constexpr (random_access_iterator<_Ip>) {
+      __i += __n;
+      return;
+    } else if constexpr (bidirectional_iterator<_Ip>) {
+      // Otherwise, if `n` is non-negative, increments `i` by `n`.
+      __advance_forward(__i, __n);
+      // Otherwise, decrements `i` by `-n`.
+      __advance_backward(__i, __n);
+      return;
+    } else {
+      // Otherwise, if `n` is non-negative, increments `i` by `n`.
+      __advance_forward(__i, __n);
+      return;
+    }
+  }
+
+  // Preconditions: Either `assignable_from<I&, S> || sized_sentinel_for<S, I>` is modeled, or [i, bound) denotes a range.
+  template <input_or_output_iterator _Ip, sentinel_for<_Ip> _Sp>
+  constexpr void operator()(_Ip& __i, _Sp __bound) const {
+    // If `I` and `S` model `assignable_from<I&, S>`, equivalent to `i = std::move(bound)`.
+    if constexpr (assignable_from<_Ip&, _Sp>) {
+      __i = std::move(__bound);
+    }
+    // Otherwise, if `S` and `I` model `sized_sentinel_for<S, I>`, equivalent to `ranges::advance(i, bound - i)`.
+    else if constexpr (sized_sentinel_for<_Sp, _Ip>) {
+      (*this)(__i, __bound - __i);
+    }
+    // Otherwise, while `bool(i != bound)` is true, increments `i`.
+    else {
+      while (__i != __bound) {
+        ++__i;
+      }
+    }
+  }
+
+  // Preconditions:
+  //   * If `n > 0`, [i, bound) denotes a range.
+  //   * If `n == 0`, [i, bound) or [bound, i) denotes a range.
+  //   * If `n < 0`, [bound, i) denotes a range, `I` models `bidirectional_iterator`, and `I` and `S` model `same_as<I, S>`.
+  // Returns: `n - M`, where `M` is the difference between the the ending and starting position.
+  template <input_or_output_iterator _Ip, sentinel_for<_Ip> _Sp>
+  constexpr iter_difference_t<_Ip> operator()(_Ip& __i, iter_difference_t<_Ip> __n, _Sp __bound) const {
+    _LIBCPP_ASSERT(__n >= 0 || (bidirectional_iterator<_Ip> && same_as<_Ip, _Sp>),
+                   "If `n < 0`, then `bidirectional_iterator<I> && same_as<I, S>` must be true.");
+    // If `S` and `I` model `sized_sentinel_for<S, I>`:
+    if constexpr (sized_sentinel_for<_Sp, _Ip>) {
+      // If |n| >= |bound - i|, equivalent to `ranges::advance(i, bound)`.
+      if (const auto __M = __bound - __i; __abs(__n) >= __abs(__M)) {
+        (*this)(__i, __bound);
+        return __n - __M;
+      }
+
+      // Otherwise, equivalent to `ranges::advance(i, n)`.
+      (*this)(__i, __n);
+      return 0;
+    } else {
+      // Otherwise, if `n` is non-negative, while `bool(i != bound)` is true, increments `i` but at
+      // most `n` times.
+      while (__i != __bound && __n > 0) {
+        ++__i;
+        --__n;
+      }
+
+      // Otherwise, while `bool(i != bound)` is true, decrements `i` but at most `-n` times.
+      if constexpr (bidirectional_iterator<_Ip> && same_as<_Ip, _Sp>) {
+        while (__i != __bound && __n < 0) {
+          --__i;
+          ++__n;
+        }
+      }
+      return __n;
+    }
+
+    _LIBCPP_UNREACHABLE();
+  }
+};
+
+inline constexpr auto advance = __advance_fn(__function_like::__tag());
+} // namespace ranges
+
+#endif // !defined(_LIBCPP_HAS_NO_RANGES)
+
+_LIBCPP_END_NAMESPACE_STD
+
+_LIBCPP_POP_MACROS
+
+#endif // _LIBCPP___ITERATOR_ADVANCE_H

libcxx/include/iterator

@@ -124,6 +124,17 @@ template <class BidirectionalIterator>  // constexpr in C++17
   constexpr BidirectionalIterator prev(BidirectionalIterator x,
     typename iterator_traits<BidirectionalIterator>::difference_type n = 1);
 
+// [range.iter.ops], range iterator operations
+namespace ranges {
+  // [range.iter.op.advance], ranges::advance
+  template<input_or_output_iterator I>
+    constexpr void advance(I& i, iter_difference_t<I> n);                          // since C++20
+  template<input_or_output_iterator I, sentinel_for<I> S>
+    constexpr void advance(I& i, S bound);                                         // since C++20
+  template<input_or_output_iterator I, sentinel_for<I> S>
+    constexpr iter_difference_t<I> advance(I& i, iter_difference_t<I> n, S bound); // since C++20
+}
+
 template <class Iterator>
 class reverse_iterator
     : public iterator<typename iterator_traits<Iterator>::iterator_category,
@@ -472,6 +483,7 @@ template <class E> constexpr const E* data(initializer_list<E> il) noexcept;
 #include <__config>
 #include <__debug>
 #include <__functional_base>
+#include <__iterator/advance.h>
 #include <__iterator/concepts.h>
 #include <__iterator/incrementable_traits.h>
 #include <__iterator/iter_move.h>
@@ -534,7 +546,8 @@ void __advance(_RandIter& __i,
    __i += __n;
 }
 
-template <class _InputIter, class _Distance>
+template <class _InputIter, class _Distance,
+          class = typename enable_if<is_integral<decltype(_VSTD::__convert_to_integral(declval<_Distance>()))>::value>::type>
 inline _LIBCPP_INLINE_VISIBILITY _LIBCPP_CONSTEXPR_AFTER_CXX14
 void advance(_InputIter& __i, _Distance __orig_n)
 {

libcxx/test/std/iterators/iterator.primitives/range.iter.ops/range.iter.ops.advance/advance.pass.cpp

@@ -0,0 +1,272 @@
+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+// UNSUPPORTED: c++03, c++11, c++14, c++17
+// UNSUPPORTED: libcpp-no-concepts
+// UNSUPPORTED: gcc-10
+
+// ranges::advance
+
+#include <iterator>
+
+#include <array>
+#include <cassert>
+
+#include "test_standard_function.h"
+#include "test_iterators.h"
+
+static_assert(is_function_like<decltype(std::ranges::advance)>());
+
+using range_t = std::array<int, 10>;
+
+[[nodiscard]] constexpr bool operator==(output_iterator<int*> const x, output_iterator<int*> const y) {
+  return x.base() == y.base();
+}
+
+template <std::input_or_output_iterator I>
+constexpr void check_round_trip(stride_counting_iterator<I> const& i, std::ptrdiff_t const n) {
+  auto const distance = n < 0 ? -n : n;
+  assert(i.stride_count() == distance);
+  assert(i.stride_displacement() == n);
+}
+
+template <std::random_access_iterator I>
+constexpr void check_round_trip(stride_counting_iterator<I> const& i, std::ptrdiff_t const n) {
+  assert(i.stride_count() == 0 || i.stride_count() == 1);
+  assert(i.stride_displacement() == n < 0 ? -1 : 1);
+}
+
+namespace iterator_count {
+template <std::input_or_output_iterator I>
+constexpr void check_move_forward(std::ptrdiff_t const n) {
+  auto range = range_t{0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
+  auto first = stride_counting_iterator(I(range.begin()));
+  std::ranges::advance(first, n);
+  assert(std::move(first).base().base() == range.begin() + n);
+  check_round_trip(first, n);
+}
+
+template <std::bidirectional_iterator I>
+constexpr void check_move_backward(std::ptrdiff_t const n) {
+  auto range = range_t{0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
+  auto first = stride_counting_iterator(I(range.begin() + n));
+  std::ranges::advance(first, -n);
+  assert(std::move(first).base().base() == range.begin());
+  check_round_trip(first, -n);
+}
+
+[[nodiscard]] constexpr bool test() {
+  check_move_forward<cpp17_input_iterator<range_t::const_iterator> >(1);
+  check_move_forward<cpp20_input_iterator<range_t::const_iterator> >(2);
+  check_move_forward<forward_iterator<range_t::const_iterator> >(3);
+  check_move_forward<bidirectional_iterator<range_t::const_iterator> >(4);
+  check_move_forward<random_access_iterator<range_t::const_iterator> >(5);
+  check_move_forward<contiguous_iterator<range_t::const_iterator> >(6);
+  check_move_forward<output_iterator<range_t::iterator> >(7);
+
+  check_move_backward<bidirectional_iterator<range_t::const_iterator> >(4);
+  check_move_backward<random_access_iterator<range_t::const_iterator> >(5);
+  check_move_backward<contiguous_iterator<range_t::const_iterator> >(6);
+
+  // Zero should be checked for each case and each overload
+  check_move_forward<cpp17_input_iterator<range_t::const_iterator> >(0);
+  check_move_forward<cpp20_input_iterator<range_t::const_iterator> >(0);
+  check_move_forward<forward_iterator<range_t::const_iterator> >(0);
+  check_move_forward<bidirectional_iterator<range_t::const_iterator> >(0);
+  check_move_forward<random_access_iterator<range_t::const_iterator> >(0);
+  check_move_forward<output_iterator<range_t::iterator> >(0);
+  check_move_backward<bidirectional_iterator<range_t::const_iterator> >(0);
+  check_move_backward<random_access_iterator<range_t::const_iterator> >(0);
+
+  return true;
+}
+} // namespace iterator_count
+
+class distance_apriori_sentinel {
+public:
+  distance_apriori_sentinel() = default;
+  constexpr explicit distance_apriori_sentinel(std::ptrdiff_t const count) : count_(count) {}
+
+  [[nodiscard]] constexpr bool operator==(std::input_or_output_iterator auto const&) const {
+    assert(false && "difference op should take precedence");
+    return false;
+  }
+
+  [[nodiscard]] constexpr friend std::ptrdiff_t operator-(std::input_or_output_iterator auto const&,
+                                                          distance_apriori_sentinel const y) {
+    return -y.count_;
+  }
+
+  [[nodiscard]] constexpr friend std::ptrdiff_t operator-(distance_apriori_sentinel const x,
+                                                          std::input_or_output_iterator auto const&) {
+    return x.count_;
+  }
+
+private:
+  std::ptrdiff_t count_ = 0;
+};
+
+namespace iterator_sentinel {
+template <std::input_or_output_iterator I, std::sentinel_for<I> S = I>
+constexpr void check_assignable_case(std::ptrdiff_t const n) {
+  auto range = range_t{0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
+  auto first = stride_counting_iterator(I(range.begin()));
+  std::ranges::advance(first, stride_counting_iterator(S(I(range.begin() + n))));
+  assert(std::move(first).base().base() == range.begin() + n);
+  assert(first.stride_count() == 0); // always zero, so don't use `check_round_trip`
+}
+
+template <std::input_or_output_iterator I>
+constexpr void check_sized_sentinel_case(std::ptrdiff_t const n) {
+  auto range = range_t{0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
+  auto first = stride_counting_iterator(I(range.begin()));
+  std::ranges::advance(first, distance_apriori_sentinel(n));
+  assert(std::move(first).base().base() == range.begin() + n);
+  check_round_trip(first, n);
+}
+
+template <std::input_or_output_iterator I>
+constexpr void check_sentinel_case(std::ptrdiff_t const n) {
+  auto range = range_t{0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
+  auto first = stride_counting_iterator(I(range.begin()));
+  auto const last = I(range.begin() + n);
+  std::ranges::advance(first, sentinel_wrapper(last));
+  assert(first.base() == last);
+  assert(first.stride_count() == n); // always `n`, so don't use `check_round_trip`
+}
+
+[[nodiscard]] constexpr bool test() {
+  check_assignable_case<cpp17_input_iterator<range_t::const_iterator> >(1);
+  check_assignable_case<forward_iterator<range_t::const_iterator> >(3);
+  check_assignable_case<bidirectional_iterator<range_t::const_iterator> >(4);
+  check_assignable_case<random_access_iterator<range_t::const_iterator> >(5);
+  check_assignable_case<contiguous_iterator<range_t::const_iterator> >(6);
+  check_assignable_case<output_iterator<range_t::iterator> >(7);
+
+  check_sized_sentinel_case<cpp17_input_iterator<range_t::const_iterator> >(7);
+  check_sized_sentinel_case<cpp20_input_iterator<range_t::const_iterator> >(6);
+  check_sized_sentinel_case<forward_iterator<range_t::const_iterator> >(5);
+  check_sized_sentinel_case<bidirectional_iterator<range_t::const_iterator> >(4);
+  check_sized_sentinel_case<random_access_iterator<range_t::const_iterator> >(3);
+  check_sized_sentinel_case<contiguous_iterator<range_t::const_iterator> >(2);
+  check_sized_sentinel_case<output_iterator<range_t::iterator> >(1);
+
+  check_sentinel_case<cpp17_input_iterator<range_t::const_iterator> >(1);
+  // cpp20_input_iterator not copyable, so is omitted
+  check_sentinel_case<forward_iterator<range_t::const_iterator> >(3);
+  check_sentinel_case<bidirectional_iterator<range_t::const_iterator> >(4);
+  check_sentinel_case<random_access_iterator<range_t::const_iterator> >(5);
+  check_sentinel_case<contiguous_iterator<range_t::const_iterator> >(6);
+  check_sentinel_case<output_iterator<range_t::iterator> >(7);
+  return true;
+}
+} // namespace iterator_sentinel
+
+namespace iterator_count_sentinel {
+struct expected_t {
+  range_t::const_iterator coordinate;
+  std::ptrdiff_t result;
+};
+
+template <std::input_or_output_iterator I>
+constexpr void check_forward_sized_sentinel_case(std::ptrdiff_t const n, expected_t const expected, range_t& range) {
+  auto current = stride_counting_iterator(I(range.begin()));
+  auto const result = std::ranges::advance(current, n, distance_apriori_sentinel(range.size()));
+  assert(current.base().base() == expected.coordinate);
+  assert(result == expected.result);
+  check_round_trip(current, n - expected.result);
+}
+
+template <std::random_access_iterator I>
+constexpr void check_backward_sized_sentinel_case(std::ptrdiff_t const n, expected_t const expected, range_t& range) {
+  auto current = stride_counting_iterator(I(range.end()));
+  auto const result = std::ranges::advance(current, -n, stride_counting_iterator(I(range.begin())));
+  assert(current.base().base() == expected.coordinate);
+  assert(result == expected.result);
+  check_round_trip(current, n - expected.result);
+}
+
+template <std::input_or_output_iterator I>
+constexpr void check_forward_case(std::ptrdiff_t const n, expected_t const expected, range_t& range) {
+  auto current = stride_counting_iterator(I(range.begin()));
+  auto const result = std::ranges::advance(current, n, sentinel_wrapper(I(range.end())));
+  assert(current.base().base() == expected.coordinate);
+  assert(result == expected.result);
+  assert(current.stride_count() == n - expected.result);
+}
+
+template <std::bidirectional_iterator I>
+constexpr void check_backward_case(std::ptrdiff_t const n, expected_t const expected, range_t& range) {
+  auto current = stride_counting_iterator(I(range.end()));
+  auto const result = std::ranges::advance(current, -n, stride_counting_iterator(I(range.begin())));
+  assert(current.base().base() == expected.coordinate);
+  assert(result == expected.result);
+  assert(current.stride_count() == n + expected.result);
+  assert(current.stride_count() == -current.stride_displacement());
+}
+
+[[nodiscard]] constexpr bool test() {
+  auto range = range_t{0, 1, 2, 3, 4, 5, 6, 7, 8, 9};
+  check_forward_sized_sentinel_case<cpp17_input_iterator<range_t::const_iterator> >(1, {range.begin() + 1, 0}, range);
+  // cpp20_input_iterator not copyable, so is omitted
+  check_forward_sized_sentinel_case<forward_iterator<range_t::const_iterator> >(3, {range.begin() + 3, 0}, range);
+  check_forward_sized_sentinel_case<bidirectional_iterator<range_t::const_iterator> >(4, {range.begin() + 4, 0}, range);
+  check_forward_sized_sentinel_case<random_access_iterator<range_t::const_iterator> >(5, {range.begin() + 5, 0}, range);
+  check_forward_sized_sentinel_case<contiguous_iterator<range_t::const_iterator> >(6, {range.begin() + 6, 0}, range);
+  check_forward_sized_sentinel_case<output_iterator<range_t::iterator> >(7, {range.begin() + 7, 0}, range);
+
+  // bidirectional_iterator omitted because `n < 0` case requires `same_as<I, S>`
+  check_backward_sized_sentinel_case<random_access_iterator<range_t::const_iterator> >(5, {range.begin() + 5, 0},
+                                                                                       range);
+  check_backward_sized_sentinel_case<contiguous_iterator<range_t::const_iterator> >(6, {range.begin() + 4, 0}, range);
+
+  // disntance == range.size()
+  check_forward_sized_sentinel_case<forward_iterator<range_t::const_iterator> >(10, {range.end(), 0}, range);
+  check_forward_sized_sentinel_case<output_iterator<range_t::iterator> >(10, {range.end(), 0}, range);
+  check_backward_sized_sentinel_case<random_access_iterator<range_t::const_iterator> >(10, {range.begin(), 0}, range);
+
+  // distance > range.size()
+  check_forward_sized_sentinel_case<forward_iterator<range_t::const_iterator> >(1000, {range.end(), 990}, range);
+  check_forward_sized_sentinel_case<output_iterator<range_t::iterator> >(1000, {range.end(), 990}, range);
+  check_backward_sized_sentinel_case<random_access_iterator<range_t::const_iterator> >(1000, {range.begin(), -990},
+                                                                                       range);
+
+  check_forward_case<cpp17_input_iterator<range_t::const_iterator> >(1, {range.begin() + 1, 0}, range);
+  check_forward_case<forward_iterator<range_t::const_iterator> >(3, {range.begin() + 3, 0}, range);
+  check_forward_case<bidirectional_iterator<range_t::const_iterator> >(4, {range.begin() + 4, 0}, range);
+  check_forward_case<random_access_iterator<range_t::const_iterator> >(5, {range.begin() + 5, 0}, range);
+  check_forward_case<contiguous_iterator<range_t::const_iterator> >(6, {range.begin() + 6, 0}, range);
+  check_forward_case<output_iterator<range_t::iterator> >(7, {range.begin() + 7, 0}, range);
+  check_backward_case<bidirectional_iterator<range_t::const_iterator> >(8, {range.begin() + 2, 0}, range);
+
+  // disntance == range.size()
+  check_forward_case<forward_iterator<range_t::const_iterator> >(10, {range.end(), 0}, range);
+  check_forward_case<output_iterator<range_t::iterator> >(10, {range.end(), 0}, range);
+  check_backward_case<bidirectional_iterator<range_t::const_iterator> >(10, {range.begin(), 0}, range);
+
+  // distance > range.size()
+  check_forward_case<forward_iterator<range_t::const_iterator> >(1000, {range.end(), 990}, range);
+  check_forward_case<output_iterator<range_t::iterator> >(1000, {range.end(), 990}, range);
+  check_backward_case<bidirectional_iterator<range_t::const_iterator> >(1000, {range.begin(), -990}, range);
+
+  return true;
+}
+} // namespace iterator_count_sentinel
+
+int main(int, char**) {
+  static_assert(iterator_count::test());
+  assert(iterator_count::test());
+
+  static_assert(iterator_sentinel::test());
+  assert(iterator_sentinel::test());
+
+  static_assert(iterator_count_sentinel::test());
+  assert(iterator_count_sentinel::test());
+
+  return 0;
+}

libcxx/test/std/iterators/iterator.primitives/range.iter.ops/range.iter.ops.advance/constraints.verify.cpp

@@ -0,0 +1,26 @@
+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+// UNSUPPORTED: c++03, c++11, c++14, c++17
+// UNSUPPORTED: libcpp-no-concepts
+// UNSUPPORTED: gcc-10
+
+// ranges::next
+
+#include <iterator>
+
+#include <memory>
+
+#include "test_iterators.h"
+
+void proper_constraints() {
+  auto p = std::unique_ptr<int>();
+  std::ranges::advance(p, 5); // expected-error {{no matching function for call}}
+  std::ranges::advance(p, p); // expected-error {{no matching function for call}}
+  std::ranges::advance(p, 5, p); // expected-error {{no matching function for call}}
+}

libcxx/test/std/iterators/iterator.primitives/range.iter.ops/range.iter.ops.advance/special_function.compile.pass.cpp

@@ -0,0 +1,90 @@
+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+// UNSUPPORTED: c++03, c++11, c++14, c++17
+// UNSUPPORTED: libcpp-no-concepts
+// UNSUPPORTED: gcc-10
+
+// ranges::advance
+
+#include <iterator>
+
+// FIXME: We're bending the rules here by adding a new type to namespace std::ranges. Since this is
+// the standard library's test suite, this should be fine (we *are* the implementation), but it's
+// necessary at the time of writing since there aren't any iterators in std::ranges that we can
+// borrow for this test.
+namespace std::ranges {
+class fake_forward_iterator {
+public:
+  using value_type = int;
+  using difference_type = std::ptrdiff_t;
+  using iterator_category = std::forward_iterator_tag;
+
+  fake_forward_iterator() = default;
+
+  value_type operator*() const;
+  fake_forward_iterator& operator++();
+  fake_forward_iterator operator++(int);
+
+  bool operator==(fake_forward_iterator const&) const = default;
+};
+} // namespace std::ranges
+
+template <class I, class... Args>
+constexpr bool unqualified_lookup_works = requires(I i, Args... args) {
+  advance(i, args...);
+};
+
+static_assert(!unqualified_lookup_works<std::ranges::fake_forward_iterator, std::ptrdiff_t>);
+static_assert(!unqualified_lookup_works<std::ranges::fake_forward_iterator, std::ranges::fake_forward_iterator>);
+static_assert(
+    !unqualified_lookup_works<std::ranges::fake_forward_iterator, std::ptrdiff_t, std::ranges::fake_forward_iterator>);
+
+namespace test {
+template <class>
+class forward_iterator {
+public:
+  using value_type = int;
+  using difference_type = std::ptrdiff_t;
+  using iterator_category = std::forward_iterator_tag;
+
+  forward_iterator() = default;
+
+  value_type operator*() const;
+  forward_iterator& operator++();
+  forward_iterator operator++(int);
+
+  bool operator==(forward_iterator const&) const = default;
+};
+
+template <class I>
+void advance(forward_iterator<I>&, std::ptrdiff_t) {
+  static_assert(std::same_as<I, I*>);
+}
+
+template <class I>
+void advance(forward_iterator<I>&, forward_iterator<I>) {
+  static_assert(std::same_as<I, I*>);
+}
+
+template <class I>
+void advance(forward_iterator<I>&, std::ptrdiff_t, forward_iterator<I>) {
+  static_assert(std::same_as<I, I*>);
+}
+} // namespace test
+
+// When found by unqualified ([basic.lookup.unqual]) name lookup for the postfix-expression in a
+// function call ([expr.call]), they inhibit argument-dependent name lookup.
+void adl_inhibition() {
+  test::forward_iterator<int*> x;
+
+  using std::ranges::advance;
+  advance(x, 0);
+  advance(x, x);
+  advance(x, 0, x);
+}

libcxx/test/support/test_iterators.h

@@ -636,6 +636,8 @@ bool operator!= (const NonThrowingIterator<T>& a, const NonThrowingIterator<T>&
 
 #ifdef TEST_SUPPORTS_RANGES
 
+// clang-format off
+
 template <class I>
 struct cpp20_input_iterator {
   using value_type = std::iter_value_t<I>;
@@ -654,21 +656,226 @@ struct cpp20_input_iterator {
 
   constexpr decltype(auto) operator*() const { return *base_; }
 
-  cpp20_input_iterator& operator++() {
+  constexpr cpp20_input_iterator& operator++() {
     ++base_;
     return *this;
   }
 
-  void operator++(int) { ++base_; }
+  constexpr void operator++(int) { ++base_; }
 
-  [[nodiscard]] I const& base() const& { return base_; }
+  [[nodiscard]] constexpr I const& base() const& { return base_; }
 
-  [[nodiscard]] I base() && { return std::move(base_); }
+  [[nodiscard]] constexpr I base() && { return std::move(base_); }
 
 private:
   I base_ = I();
 };
 
+template <std::input_or_output_iterator I>
+struct iterator_concept {
+  using type = std::output_iterator_tag;
+};
+
+template <std::input_iterator I>
+struct iterator_concept<I> {
+  using type = std::input_iterator_tag;
+};
+
+template <std::forward_iterator I>
+struct iterator_concept<I> {
+  using type = std::forward_iterator_tag;
+};
+
+template <std::bidirectional_iterator I>
+struct iterator_concept<I> {
+  using type = std::bidirectional_iterator_tag;
+};
+
+template <std::random_access_iterator I>
+struct iterator_concept<I> {
+  using type = std::random_access_iterator_tag;
+};
+
+template<std::contiguous_iterator I>
+struct iterator_concept<I> {
+  using type = std::contiguous_iterator_tag;
+};
+
+template <std::input_or_output_iterator I>
+using iterator_concept_t = typename iterator_concept<I>::type;
+
+template<std::input_or_output_iterator>
+struct iter_value_or_void { using type = void; };
+
+template<std::input_iterator I>
+struct iter_value_or_void<I> {
+  using type = std::iter_value_t<I>;
+};
+
+// Iterator adaptor that counts the number of times the iterator has had a successor/predecessor
+// operation called. Has two recorders:
+// * `stride_count`, which records the total number of calls to an op++, op--, op+=, or op-=.
+// * `stride_displacement`, which records the displacement of the calls. This means that both
+//   op++/op+= will increase the displacement counter by 1, and op--/op-= will decrease the
+//   displacement counter by 1.
+template <std::input_or_output_iterator I>
+class stride_counting_iterator {
+public:
+  using value_type = typename iter_value_or_void<I>::type;
+  using difference_type = std::iter_difference_t<I>;
+  using iterator_concept = iterator_concept_t<I>;
+
+  stride_counting_iterator() = default;
+
+  constexpr explicit stride_counting_iterator(I current) : base_(std::move(current)) {}
+
+  [[nodiscard]] constexpr I const& base() const& requires std::copyable<I> { return base_; }
+
+  [[nodiscard]] constexpr I base() && { return std::move(base_); }
+
+  constexpr difference_type stride_count() const { return stride_count_; }
+
+  constexpr difference_type stride_displacement() const { return stride_displacement_; }
+
+  constexpr decltype(auto) operator*() const { return *base_; }
+
+  constexpr decltype(auto) operator[](difference_type const n) const { return base_[n]; }
+
+  constexpr stride_counting_iterator& operator++()
+  {
+    ++base_;
+    ++stride_count_;
+    ++stride_displacement_;
+    return *this;
+  }
+
+  constexpr void operator++(int) { ++*this; }
+
+  constexpr stride_counting_iterator operator++(int)
+  requires std::forward_iterator<I>
+  {
+    auto temp = *this;
+    ++*this;
+    return temp;
+  }
+
+  constexpr stride_counting_iterator& operator--()
+  requires std::bidirectional_iterator<I>
+  {
+    --base_;
+    ++stride_count_;
+    --stride_displacement_;
+    return *this;
+  }
+
+  constexpr stride_counting_iterator operator--(int)
+  requires std::bidirectional_iterator<I>
+  {
+    auto temp = *this;
+    --*this;
+    return temp;
+  }
+
+  constexpr stride_counting_iterator& operator+=(difference_type const n)
+  requires std::random_access_iterator<I>
+  {
+    base_ += n;
+    ++stride_count_;
+    ++stride_displacement_;
+    return *this;
+  }
+
+  constexpr stride_counting_iterator& operator-=(difference_type const n)
+  requires std::random_access_iterator<I>
+  {
+    base_ -= n;
+    ++stride_count_;
+    --stride_displacement_;
+    return *this;
+  }
+
+  constexpr friend stride_counting_iterator operator+(stride_counting_iterator i, difference_type const n)
+  requires std::random_access_iterator<I>
+  {
+    return i += n;
+  }
+
+  constexpr friend stride_counting_iterator operator+(difference_type const n, stride_counting_iterator i)
+  requires std::random_access_iterator<I>
+  {
+    return i += n;
+  }
+
+  constexpr friend stride_counting_iterator operator-(stride_counting_iterator i, difference_type const n)
+  requires std::random_access_iterator<I>
+  {
+    return i -= n;
+  }
+
+  constexpr friend difference_type operator-(stride_counting_iterator const& x, stride_counting_iterator const& y)
+  requires std::sized_sentinel_for<I, I>
+  {
+    return x.base() - y.base();
+  }
+
+  constexpr bool operator==(stride_counting_iterator const& other) const
+  requires std::sentinel_for<I, I>
+  {
+    return base_ == other.base_;
+  }
+
+  template <std::sentinel_for<I> S>
+  constexpr bool operator==(S const last) const
+  {
+      return base_ == last;
+  }
+
+  constexpr friend bool operator<(stride_counting_iterator const& x, stride_counting_iterator const& y)
+  requires std::random_access_iterator<I>
+  {
+    return x.base_ < y.base_;
+  }
+
+  constexpr friend bool operator>(stride_counting_iterator const& x, stride_counting_iterator const& y)
+  requires std::random_access_iterator<I>
+  {
+    return y < x;
+  }
+
+  constexpr friend bool operator<=(stride_counting_iterator const& x, stride_counting_iterator const& y)
+  requires std::random_access_iterator<I>
+  {
+    return !(y < x);
+  }
+
+  constexpr friend bool operator>=(stride_counting_iterator const& x, stride_counting_iterator const& y)
+  requires std::random_access_iterator<I>
+  {
+    return !(x < y);
+  }
+
+private:
+  I base_;
+  difference_type stride_count_ = 0;
+  difference_type stride_displacement_ = 0;
+};
+
+template <std::input_or_output_iterator I>
+class sentinel_wrapper {
+public:
+  sentinel_wrapper() = default;
+  constexpr explicit sentinel_wrapper(I base) : base_(std::move(base)) {}
+
+  constexpr bool operator==(I const& other) const requires std::equality_comparable<I> {
+    return base_ == other;
+  }
+
+private:
+  I base_ = I();
+};
+
+// clang-format on
+
 #endif // TEST_STD_VER > 17 && defined(__cpp_lib_concepts)
 
 #undef DELETE_FUNCTION

libcxx/test/support/test_standard_function.h

@@ -0,0 +1,39 @@
+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+#ifndef LIBCXX_TEST_SUPPORT_TEST_STANDARD_FUNCTION_H
+#define LIBCXX_TEST_SUPPORT_TEST_STANDARD_FUNCTION_H
+
+#include "test_macros.h"
+
+#if TEST_STD_VER >= 20
+template <class T>
+constexpr bool is_addressable = requires(T t) {
+  &t;
+};
+
+template <class T>
+[[nodiscard]] constexpr bool is_function_like() {
+  using X = std::remove_cvref_t<T>;
+  static_assert(!is_addressable<X>);
+  static_assert(!is_addressable<X const>);
+
+  static_assert(std::destructible<X> && !std::default_initializable<X>);
+
+  static_assert(!std::move_constructible<X>);
+  static_assert(!std::assignable_from<X&, X>);
+
+  static_assert(!std::copy_constructible<X>);
+  static_assert(!std::assignable_from<X&, X const>);
+  static_assert(!std::assignable_from<X&, X&>);
+  static_assert(!std::assignable_from<X&, X const&>);
+  static_assert(std::is_final_v<X>);
+  return true;
+}
+#endif
+
+#endif // LIBCXX_TEST_SUPPORT_TEST_STANDARD_FUNCTION_H