[libc++] LWG3672: common_iterator::operator->() should return by value (#87899)

## Abstract

This pull request implements LWG3672: `common_iterator::operator->()`
should return by value. The current implementation specifies that this
function should return the underlying pointer by reference (`T*
const&`), but it would be more intuitive to return it by value (`T*`).

## Reference

- [Draft C++ Standard:
[common.iter.access]](https://eel.is/c++draft/common.iter.access)
- [LWG3672](https://cplusplus.github.io/LWG/issue3672)

Author: Xiaoyang Liu

libcxx/docs/Status/Cxx23Issues.csv

@@ -165,7 +165,7 @@
 "`3659 <https://wg21.link/LWG3659>`__","Consider ``ATOMIC_FLAG_INIT`` undeprecation","July 2022","|Complete|","15.0"
 "`3670 <https://wg21.link/LWG3670>`__","``Cpp17InputIterators`` don't have integer-class difference types","July 2022","","","|ranges|"
 "`3671 <https://wg21.link/LWG3671>`__","``atomic_fetch_xor`` missing from ``stdatomic.h``","July 2022","",""
-"`3672 <https://wg21.link/LWG3672>`__","``common_iterator::operator->()`` should return by value","July 2022","","","|ranges|"
+"`3672 <https://wg21.link/LWG3672>`__","``common_iterator::operator->()`` should return by value","July 2022","|Complete|","19.0","|ranges|"
 "`3683 <https://wg21.link/LWG3683>`__","``operator==`` for ``polymorphic_allocator`` cannot deduce template argument in common cases","July 2022","",""
 "`3687 <https://wg21.link/LWG3687>`__","``expected<cv void, E>`` move constructor should move","July 2022","|Complete|","16.0"
 "`3692 <https://wg21.link/LWG3692>`__","``zip_view::iterator``'s ``operator<=>`` is overconstrained","July 2022","","","|ranges| |spaceship|"

libcxx/include/__iterator/common_iterator.h

@@ -124,7 +124,7 @@ class common_iterator {
   }
 
   template <class _I2 = _Iter>
-  _LIBCPP_HIDE_FROM_ABI decltype(auto) operator->() const
+  _LIBCPP_HIDE_FROM_ABI auto operator->() const
     requires indirectly_readable<const _I2> && (requires(const _I2& __i) {
                __i.operator->();
              } || is_reference_v<iter_reference_t<_I2>> || constructible_from<iter_value_t<_I2>, iter_reference_t<_I2>>)

libcxx/test/std/iterators/predef.iterators/iterators.common/arrow.pass.cpp

@@ -8,7 +8,7 @@
 
 // UNSUPPORTED: c++03, c++11, c++14, c++17
 
-// decltype(auto) operator->() const
+// auto operator->() const
 //   requires see below;
 
 #include <iterator>
@@ -28,11 +28,11 @@ void test() {
       using Common = std::common_iterator<Iterator, sentinel_wrapper<Iterator>>;
 
       Common common(iter);
-      std::same_as<Iterator> auto result = common.operator->();
+      std::same_as<Iterator> decltype(auto) result = common.operator->();
       assert(base(result) == buffer);
 
       Common const ccommon(iter);
-      std::same_as<Iterator> auto cresult = ccommon.operator->();
+      std::same_as<Iterator> decltype(auto) cresult = ccommon.operator->();
       assert(base(cresult) == buffer);
     };
 
@@ -48,11 +48,11 @@ void test() {
       using Common = std::common_iterator<Iterator, sentinel_type<int*>>;
 
       Common common(iter);
-      std::same_as<int*> auto result = common.operator->();
+      std::same_as<int*> decltype(auto) result = common.operator->();
       assert(result == buffer);
 
       Common const ccommon(iter);
-      std::same_as<int*> auto cresult = ccommon.operator->();
+      std::same_as<int*> decltype(auto) cresult = ccommon.operator->();
       assert(cresult == buffer);
     };
 
@@ -72,14 +72,14 @@ void test() {
       using Common = std::common_iterator<Iterator, sentinel_type<int*>>;
 
       Common common(iter);
-      auto proxy = common.operator->();
-      std::same_as<int const*> auto result = proxy.operator->();
+      auto proxy                                     = common.operator->();
+      std::same_as<int const*> decltype(auto) result = proxy.operator->();
       assert(result != buffer); // we copied to a temporary proxy
       assert(*result == *buffer);
 
       Common const ccommon(iter);
-      auto cproxy = ccommon.operator->();
-      std::same_as<int const*> auto cresult = cproxy.operator->();
+      auto cproxy                                     = ccommon.operator->();
+      std::same_as<int const*> decltype(auto) cresult = cproxy.operator->();
       assert(cresult != buffer); // we copied to a temporary proxy
       assert(*cresult == *buffer);
     };