[libcxx][ranges] Add `unreachable_sentinel`.

[zoecarver]

Generate private header tests.

[• Quuxplusone]

LGTM % nits.

libcxx/include/iterator

406–409

Swap this down to below [iterators.counted], to match https://eel.is/c++draft/iterator.synopsis

libcxx/test/std/iterators/predef.iterators/unreachable.sentinel/unreachable_sentinel.pass.cpp

30–38

I'd test both normal and reversed comparisons, and equality and inequality, and at least one trivial SFINAE-friendliness test and noexceptness test. I.e. I'd replace this with some variation on

constexpr bool test() {

auto sentinel = std::unreachable_sentinel;
int i = 42;
assert(i != sentinel);
assert(sentinel != i);
assert(!(i == sentinel));
assert(!(sentinel == i));

assert(&i != sentinel);
assert(sentinel != &i);
assert(!(&i == sentinel));
assert(!(sentinel == &i));

int *p = nullptr;
assert(p != sentinel);
assert(sentinel != p);
assert(!(p == sentinel));
assert(!(sentinel == p));

assert( std::equality_comparable_with<std::unreachable_sentinel_t, int>);
assert( std::equality_comparable_with<std::unreachable_sentinel_t, int*>);
assert(!std::equality_comparable_with<std::unreachable_sentinel_t, void*>);
ASSERT_NOEXCEPT(sentinel == p);
ASSERT_NOEXCEPT(sentinel != p);

return true;
}

and remember to do the usual test(); static_assert(test()); dance.

[ldionne]

LGTM but please implement Arthur's comments, I agree with everything. Also, is there something that needs updating in the paper status?

I don't need to see this again.

[cjdb]

What the others have said.

[zoecarver]

Also, is there something that needs updating in the paper status?

I can't find anything.

Thanks for the reviews everyone. Thanks for the tests Arthur.

libcxx/include/CMakeLists.txt

set(files
   __iterator/ostream_iterator.h
   __iterator/ostreambuf_iterator.h
   __iterator/prev.h
   __iterator/projected.h
   __iterator/readable_traits.h
   __iterator/reverse_access.h
   __iterator/reverse_iterator.h
   __iterator/size.h
+  __iterator/unreachable_sentinel.h
   __iterator/wrap_iter.h
   __libcpp_version
   __locale
   __memory/addressof.h
   __memory/allocation_guard.h
   __memory/allocator_arg_t.h
   __memory/allocator_traits.h
   __memory/allocator.h

libcxx/include/__iterator/unreachable_sentinel.h

+// -*- 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_UNREACHABLE_SENTINEL_H
+#define _LIBCPP___ITERATOR_UNREACHABLE_SENTINEL_H
+
+#include <__config>
+#include <__iterator/concepts.h>
+
+#if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
+#pragma GCC system_header
+#endif
+
+_LIBCPP_BEGIN_NAMESPACE_STD
+
+#if !defined(_LIBCPP_HAS_NO_RANGES)
+
+struct unreachable_sentinel_t {
+  template<weakly_incrementable _Iter>
+  _LIBCPP_HIDE_FROM_ABI
+  friend constexpr bool operator==(unreachable_sentinel_t, const _Iter&) noexcept {
+    return false;
+  }
+};
+
+inline constexpr unreachable_sentinel_t unreachable_sentinel{};
+
+#endif // !defined(_LIBCPP_HAS_NO_RANGES)
+
+_LIBCPP_END_NAMESPACE_STD
+
+#endif // _LIBCPP___ITERATOR_UNREACHABLE_SENTINEL_H

libcxx/include/iterator

 
 template <class Iterator>   // constexpr in C++17
 constexpr  move_iterator<Iterator> make_move_iterator(const Iterator& i);
 
 // [default.sentinel], default sentinel
 struct default_sentinel_t;
 inline constexpr default_sentinel_t default_sentinel{};
 
 // [iterators.counted], counted iterators
 template<input_or_output_iterator I> class counted_iterator;
 
 template<input_iterator I>
   requires see below
   struct iterator_traits<counted_iterator<I>>;
 
+// [unreachable.sentinel], unreachable sentinel
+struct unreachable_sentinel_t;
+inline constexpr unreachable_sentinel_t unreachable_sentinel{};
+
 template <class T, class charT = char, class traits = char_traits<charT>, class Distance = ptrdiff_t>
 class istream_iterator
     : public iterator<input_iterator_tag, T, Distance, const T*, const T&> // until C++17
 {
 public:
     typedef input_iterator_tag           iterator_category;
     typedef T                            value_type;
     typedef Distance                     difference_type;

 #include <__iterator/ostreambuf_iterator.h>
 #include <__iterator/ostream_iterator.h>
 #include <__iterator/prev.h>
 #include <__iterator/projected.h>
 #include <__iterator/readable_traits.h>
 #include <__iterator/reverse_access.h>
 #include <__iterator/reverse_iterator.h>
 #include <__iterator/size.h>
+#include <__iterator/unreachable_sentinel.h>
 #include <__iterator/wrap_iter.h>
 #include <__memory/addressof.h>
 #include <__memory/pointer_traits.h>
 #include <__utility/forward.h>
 #include <compare>
 #include <concepts> // Mandated by the Standard.
 #include <cstddef>
 #include <initializer_list>
 #include <type_traits>
 #include <version>
 
 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
 #pragma GCC system_header
 #endif
 
 #endif // _LIBCPP_ITERATOR

libcxx/include/module.modulemap

module __iterator {
         private header "__iterator/prev.h"
         export __function_like
       }
       module projected             { private header "__iterator/projected.h" }
       module readable_traits       { private header "__iterator/readable_traits.h" }
       module reverse_access        { private header "__iterator/reverse_access.h" }
       module reverse_iterator      { private header "__iterator/reverse_iterator.h" }
       module size                  { private header "__iterator/size.h" }
+      module unreachable_sentinel  { private header "__iterator/unreachable_sentinel.h" }
       module wrap_iter             { private header "__iterator/wrap_iter.h" }
     }
   }
   module latch {
     requires cplusplus14
     header "latch"
     export *
   }

libcxx/test/libcxx/diagnostics/detail.headers/iterator/unreachable_sentinel.module.verify.cpp

+// -*- 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
+//
+//===----------------------------------------------------------------------===//
+
+// REQUIRES: modules-build
+
+// WARNING: This test was generated by 'generate_private_header_tests.py'
+// and should not be edited manually.
+
+// expected-error@*:* {{use of private header from outside its module: '__iterator/unreachable_sentinel.h'}}
+#include <__iterator/unreachable_sentinel.h>

libcxx/test/std/iterators/predef.iterators/unreachable.sentinel/unreachable_sentinel.pass.cpp

+//===----------------------------------------------------------------------===//
+//
+// 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
+
+// struct unreachable_sentinel_t;
+// inline constexpr unreachable_sentinel_t unreachable_sentinel;
+
+#include <iterator>
+
+#include <cassert>
+#include <concepts>
+#include <type_traits>
+
+#include "test_macros.h"
+
+template<class T, class U>
+concept weakly_equality_comparable_with = requires(const T& t, const U& u) {
+  { t == u } -> std::same_as<bool>;
+  { t != u } -> std::same_as<bool>;
+  { u == t } -> std::same_as<bool>;
+  { u != t } -> std::same_as<bool>;
+};
+
+constexpr bool test() {
+  static_assert(std::is_empty_v<std::unreachable_sentinel_t>);
+  static_assert(std::semiregular<std::unreachable_sentinel_t>);
+
+  static_assert(std::same_as<decltype(std::unreachable_sentinel), const std::unreachable_sentinel_t>);
+
+  auto sentinel = std::unreachable_sentinel;
+  int i = 42;
+  assert(i != sentinel);
+  assert(sentinel != i);
+  assert(!(i == sentinel));
+  assert(!(sentinel == i));
+
+  assert(&i != sentinel);
+  assert(sentinel != &i);
+  assert(!(&i == sentinel));
+  assert(!(sentinel == &i));
+
+  int *p = nullptr;
+  assert(p != sentinel);
+  assert(sentinel != p);
+  assert(!(p == sentinel));
+  assert(!(sentinel == p));
+
+  static_assert( weakly_equality_comparable_with<std::unreachable_sentinel_t, int>);
+  static_assert( weakly_equality_comparable_with<std::unreachable_sentinel_t, int*>);
+  static_assert(!weakly_equality_comparable_with<std::unreachable_sentinel_t, void*>);
+  ASSERT_NOEXCEPT(sentinel == p);
+  ASSERT_NOEXCEPT(sentinel != p);
+
+  return true;
+}
+
+int main(int, char**) {
+  test();
+  static_assert(test());
+
+  return 0;
+}