[libcxx][nfc] moves std `advance`, `next`, and `prev` into their headers

[ldionne]

I'm not a big fan of putting std::advance and std::ranges::advance in the same header - they are related but at the same time, they are fundamentally different things and have different dependencies. That's one reason why I preferred to split ranges:: things into <__ranges/XXXX.h> instead. But I guess this will do, we can adjust in the future if need be.

[cjdb]

In D103329#2789540, @ldionne wrote:

I'm not a big fan of putting std::advance and std::ranges::advance in the same header - they are related but at the same time, they are fundamentally different things and have different dependencies. That's one reason why I preferred to split ranges:: things into <__ranges/XXXX.h> instead. But I guess this will do, we can adjust in the future if need be.

Whatever we decide, it's better to keep <iterator> things inside __iterator/ wherever possible (i.e. we should probably do <__iterator/ranges/XXXX.h>, not <__ranges/XXXX.h>).

libcxx/include/__iterator/advance.h

 #pragma GCC system_header
 #endif
 
 _LIBCPP_PUSH_MACROS
 #include <__undef_macros>
 
 _LIBCPP_BEGIN_NAMESPACE_STD
 
+template <class _InputIter>
+inline _LIBCPP_INLINE_VISIBILITY _LIBCPP_CONSTEXPR_AFTER_CXX14 void
+__advance(_InputIter& __i, typename iterator_traits<_InputIter>::difference_type __n, input_iterator_tag) {
+  for (; __n > 0; --__n)
+    ++__i;
+}
+
+template <class _BiDirIter>
+inline _LIBCPP_INLINE_VISIBILITY _LIBCPP_CONSTEXPR_AFTER_CXX14 void
+__advance(_BiDirIter& __i, typename iterator_traits<_BiDirIter>::difference_type __n, bidirectional_iterator_tag) {
+  if (__n >= 0)
+    for (; __n > 0; --__n)
+      ++__i;
+  else
+    for (; __n < 0; ++__n)
+      --__i;
+}
+
+template <class _RandIter>
+inline _LIBCPP_INLINE_VISIBILITY _LIBCPP_CONSTEXPR_AFTER_CXX14 void
+__advance(_RandIter& __i, typename iterator_traits<_RandIter>::difference_type __n, random_access_iterator_tag) {
+  __i += __n;
+}
+
+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) {
+  typedef decltype(_VSTD::__convert_to_integral(__orig_n)) _IntegralSize;
+  _IntegralSize __n = __orig_n;
+  _LIBCPP_ASSERT(__n >= 0 || __is_cpp17_bidirectional_iterator<_InputIter>::value,
+                 "Attempt to advance(it, n) with negative n on a non-bidirectional iterator");
+  _VSTD::__advance(__i, __n, typename iterator_traits<_InputIter>::iterator_category());
+}
+
 #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 {

libcxx/include/__iterator/next.h

 #pragma GCC system_header
 #endif
 
 _LIBCPP_PUSH_MACROS
 #include <__undef_macros>
 
 _LIBCPP_BEGIN_NAMESPACE_STD
 
+template <class _InputIter>
+inline _LIBCPP_INLINE_VISIBILITY _LIBCPP_CONSTEXPR_AFTER_CXX14
+    typename enable_if<__is_cpp17_input_iterator<_InputIter>::value, _InputIter>::type
+    next(_InputIter __x, typename iterator_traits<_InputIter>::difference_type __n = 1) {
+  _LIBCPP_ASSERT(__n >= 0 || __is_cpp17_bidirectional_iterator<_InputIter>::value,
+                 "Attempt to next(it, n) with negative n on a non-bidirectional iterator");
+
+  _VSTD::advance(__x, __n);
+  return __x;
+}
+
 #if !defined(_LIBCPP_HAS_NO_RANGES)
 
 namespace ranges {
 struct __next_fn final : private __function_like {
   constexpr explicit __next_fn(__tag __x) noexcept : __function_like(__x) {}
 
   template <input_or_output_iterator _Ip>
   constexpr _Ip operator()(_Ip __x) const {

libcxx/include/__iterator/prev.h

 #pragma GCC system_header
 #endif
 
 _LIBCPP_PUSH_MACROS
 #include <__undef_macros>
 
 _LIBCPP_BEGIN_NAMESPACE_STD
 
+template <class _InputIter>
+inline _LIBCPP_INLINE_VISIBILITY _LIBCPP_CONSTEXPR_AFTER_CXX14
+    typename enable_if<__is_cpp17_input_iterator<_InputIter>::value, _InputIter>::type
+    prev(_InputIter __x, typename iterator_traits<_InputIter>::difference_type __n = 1) {
+  _LIBCPP_ASSERT(__n <= 0 || __is_cpp17_bidirectional_iterator<_InputIter>::value,
+                 "Attempt to prev(it, n) with a positive n on a non-bidirectional iterator");
+  _VSTD::advance(__x, -__n);
+  return __x;
+}
+
 #if !defined(_LIBCPP_HAS_NO_RANGES)
 
 namespace ranges {
 struct __prev_fn final : private __function_like {
   constexpr explicit __prev_fn(__tag __x) noexcept : __function_like(__x) {}
 
   template <bidirectional_iterator _Ip>
   constexpr _Ip operator()(_Ip __x) const {

libcxx/include/iterator

struct _LIBCPP_TEMPLATE_VIS _LIBCPP_DEPRECATED_IN_CXX17 iterator
     typedef _Distance  difference_type;
     typedef _Pointer   pointer;
     typedef _Reference reference;
     typedef _Category  iterator_category;
 };
 
 template <class _InputIter>
 inline _LIBCPP_INLINE_VISIBILITY _LIBCPP_CONSTEXPR_AFTER_CXX14
-void __advance(_InputIter& __i,
-             typename iterator_traits<_InputIter>::difference_type __n, input_iterator_tag)
-{
-    for (; __n > 0; --__n)
-        ++__i;
-}
-
-template <class _BiDirIter>
-inline _LIBCPP_INLINE_VISIBILITY _LIBCPP_CONSTEXPR_AFTER_CXX14
-void __advance(_BiDirIter& __i,
-             typename iterator_traits<_BiDirIter>::difference_type __n, bidirectional_iterator_tag)
-{
-    if (__n >= 0)
-        for (; __n > 0; --__n)
-            ++__i;
-    else
-        for (; __n < 0; ++__n)
-            --__i;
-}
-
-template <class _RandIter>
-inline _LIBCPP_INLINE_VISIBILITY _LIBCPP_CONSTEXPR_AFTER_CXX14
-void __advance(_RandIter& __i,
-             typename iterator_traits<_RandIter>::difference_type __n, random_access_iterator_tag)
-{
-   __i += __n;
-}
-
-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)
-{
-    typedef decltype(_VSTD::__convert_to_integral(__orig_n)) _IntegralSize;
-    _IntegralSize __n = __orig_n;
-    _LIBCPP_ASSERT(__n >= 0 || __is_cpp17_bidirectional_iterator<_InputIter>::value,
-                   "Attempt to advance(it, n) with negative n on a non-bidirectional iterator");
-    _VSTD::__advance(__i, __n, typename iterator_traits<_InputIter>::iterator_category());
-}
-
-template <class _InputIter>
-inline _LIBCPP_INLINE_VISIBILITY _LIBCPP_CONSTEXPR_AFTER_CXX14
 typename iterator_traits<_InputIter>::difference_type
 __distance(_InputIter __first, _InputIter __last, input_iterator_tag)
 {
     typename iterator_traits<_InputIter>::difference_type __r(0);
     for (; __first != __last; ++__first)
         ++__r;
     return __r;
 }

 template <class _InputIter>
 inline _LIBCPP_INLINE_VISIBILITY _LIBCPP_CONSTEXPR_AFTER_CXX14
 typename iterator_traits<_InputIter>::difference_type
 distance(_InputIter __first, _InputIter __last)
 {
     return _VSTD::__distance(__first, __last, typename iterator_traits<_InputIter>::iterator_category());
 }
 
-template <class _InputIter>
-inline _LIBCPP_INLINE_VISIBILITY _LIBCPP_CONSTEXPR_AFTER_CXX14
-typename enable_if
-<
-    __is_cpp17_input_iterator<_InputIter>::value,
-    _InputIter
->::type
-next(_InputIter __x,
-     typename iterator_traits<_InputIter>::difference_type __n = 1)
-{
-    _LIBCPP_ASSERT(__n >= 0 || __is_cpp17_bidirectional_iterator<_InputIter>::value,
-                       "Attempt to next(it, n) with negative n on a non-bidirectional iterator");
-
-    _VSTD::advance(__x, __n);
-    return __x;
-}
-
-template <class _InputIter>
-inline _LIBCPP_INLINE_VISIBILITY _LIBCPP_CONSTEXPR_AFTER_CXX14
-typename enable_if
-<
-    __is_cpp17_input_iterator<_InputIter>::value,
-    _InputIter
->::type
-prev(_InputIter __x,
-     typename iterator_traits<_InputIter>::difference_type __n = 1)
-{
-    _LIBCPP_ASSERT(__n <= 0 || __is_cpp17_bidirectional_iterator<_InputIter>::value,
-                       "Attempt to prev(it, n) with a positive n on a non-bidirectional iterator");
-    _VSTD::advance(__x, -__n);
-    return __x;
-}
-
-
 template <class _Tp, class = void>
 struct __is_stashing_iterator : false_type {};
 
 template <class _Tp>
 struct __is_stashing_iterator<_Tp, typename __void_t<typename _Tp::__stashing_iterator_tag>::type>
   : true_type {};
 
 _LIBCPP_SUPPRESS_DEPRECATED_PUSH