libstdc++
refwrap.h
Go to the documentation of this file.
1 // Implementation of std::reference_wrapper -*- C++ -*-
2 
3 // Copyright (C) 2004-2025 Free Software Foundation, Inc.
4 //
5 // This file is part of the GNU ISO C++ Library. This library is free
6 // software; you can redistribute it and/or modify it under the
7 // terms of the GNU General Public License as published by the
8 // Free Software Foundation; either version 3, or (at your option)
9 // any later version.
10 
11 // This library is distributed in the hope that it will be useful,
12 // but WITHOUT ANY WARRANTY; without even the implied warranty of
13 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 // GNU General Public License for more details.
15 
16 // Under Section 7 of GPL version 3, you are granted additional
17 // permissions described in the GCC Runtime Library Exception, version
18 // 3.1, as published by the Free Software Foundation.
19 
20 // You should have received a copy of the GNU General Public License and
21 // a copy of the GCC Runtime Library Exception along with this program;
22 // see the files COPYING3 and COPYING.RUNTIME respectively. If not, see
23 // <http://www.gnu.org/licenses/>.
24 
25 /** @file include/bits/refwrap.h
26  * This is an internal header file, included by other library headers.
27  * Do not attempt to use it directly. @headername{functional}
28  */
29 
30 #ifndef _GLIBCXX_REFWRAP_H
31 #define _GLIBCXX_REFWRAP_H 1
32 
33 #ifdef _GLIBCXX_SYSHDR
34 #pragma GCC system_header
35 #endif
36 
37 #if __cplusplus >= 201103L
38 
39 #include <bits/move.h>
40 #include <bits/invoke.h>
41 #include <bits/stl_function.h> // for unary_function and binary_function
42 
43 #if __glibcxx_reference_wrapper >= 202403L // >= C++26
44 # include <compare>
45 #endif
46 
47 namespace std _GLIBCXX_VISIBILITY(default)
48 {
49 _GLIBCXX_BEGIN_NAMESPACE_VERSION
50 
51  /// @cond undocumented
52 
53  /**
54  * Derives from @c unary_function or @c binary_function, or perhaps
55  * nothing, depending on the number of arguments provided. The
56  * primary template is the basis case, which derives nothing.
57  */
58  template<typename _Res, typename... _ArgTypes>
59  struct _Maybe_unary_or_binary_function { };
60 
61 // Ignore warnings about unary_function and binary_function.
62 #pragma GCC diagnostic push
63 #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
64 
65  /// Derives from @c unary_function, as appropriate.
66  template<typename _Res, typename _T1>
67  struct _Maybe_unary_or_binary_function<_Res, _T1>
68  : std::unary_function<_T1, _Res> { };
69 
70  /// Derives from @c binary_function, as appropriate.
71  template<typename _Res, typename _T1, typename _T2>
72  struct _Maybe_unary_or_binary_function<_Res, _T1, _T2>
73  : std::binary_function<_T1, _T2, _Res> { };
74 
75 #pragma GCC diagnostic pop
76 
77  template<typename _Signature>
78  struct _Mem_fn_traits;
79 
80  template<typename _Res, typename _Class, typename... _ArgTypes>
81  struct _Mem_fn_traits_base
82  {
83  using __result_type = _Res;
84  using __maybe_type
85  = _Maybe_unary_or_binary_function<_Res, _Class*, _ArgTypes...>;
86  using __arity = integral_constant<size_t, sizeof...(_ArgTypes)>;
87  };
88 
89 #define _GLIBCXX_MEM_FN_TRAITS2(_CV, _REF, _LVAL, _RVAL) \
90  template<typename _Res, typename _Class, typename... _ArgTypes> \
91  struct _Mem_fn_traits<_Res (_Class::*)(_ArgTypes...) _CV _REF> \
92  : _Mem_fn_traits_base<_Res, _CV _Class, _ArgTypes...> \
93  { \
94  using __vararg = false_type; \
95  }; \
96  template<typename _Res, typename _Class, typename... _ArgTypes> \
97  struct _Mem_fn_traits<_Res (_Class::*)(_ArgTypes..., ...) _CV _REF> \
98  : _Mem_fn_traits_base<_Res, _CV _Class, _ArgTypes...> \
99  { \
100  using __vararg = true_type; \
101  };
102 
103 #define _GLIBCXX_MEM_FN_TRAITS(_REF, _LVAL, _RVAL) \
104  _GLIBCXX_MEM_FN_TRAITS2( , _REF, _LVAL, _RVAL) \
105  _GLIBCXX_MEM_FN_TRAITS2(const , _REF, _LVAL, _RVAL) \
106  _GLIBCXX_MEM_FN_TRAITS2(volatile , _REF, _LVAL, _RVAL) \
107  _GLIBCXX_MEM_FN_TRAITS2(const volatile, _REF, _LVAL, _RVAL)
108 
109 _GLIBCXX_MEM_FN_TRAITS( , true_type, true_type)
110 _GLIBCXX_MEM_FN_TRAITS(&, true_type, false_type)
111 _GLIBCXX_MEM_FN_TRAITS(&&, false_type, true_type)
112 
113 #if __cplusplus > 201402L
114 _GLIBCXX_MEM_FN_TRAITS(noexcept, true_type, true_type)
115 _GLIBCXX_MEM_FN_TRAITS(& noexcept, true_type, false_type)
116 _GLIBCXX_MEM_FN_TRAITS(&& noexcept, false_type, true_type)
117 #endif
118 
119 #undef _GLIBCXX_MEM_FN_TRAITS
120 #undef _GLIBCXX_MEM_FN_TRAITS2
121 
122  /// If we have found a result_type, extract it.
123  template<typename _Functor, typename = __void_t<>>
124  struct _Maybe_get_result_type
125  { };
126 
127  template<typename _Functor>
128  struct _Maybe_get_result_type<_Functor,
129  __void_t<typename _Functor::result_type>>
130  { typedef typename _Functor::result_type result_type; };
131 
132  /**
133  * Base class for any function object that has a weak result type, as
134  * defined in 20.8.2 [func.require] of C++11.
135  */
136  template<typename _Functor>
137  struct _Weak_result_type_impl
138  : _Maybe_get_result_type<_Functor>
139  { };
140 
141  /// Retrieve the result type for a function type.
142  template<typename _Res, typename... _ArgTypes _GLIBCXX_NOEXCEPT_PARM>
143  struct _Weak_result_type_impl<_Res(_ArgTypes...) _GLIBCXX_NOEXCEPT_QUAL>
144  { typedef _Res result_type; };
145 
146  /// Retrieve the result type for a varargs function type.
147  template<typename _Res, typename... _ArgTypes _GLIBCXX_NOEXCEPT_PARM>
148  struct _Weak_result_type_impl<_Res(_ArgTypes...,
149  ...) _GLIBCXX_NOEXCEPT_QUAL>
150  { typedef _Res result_type; };
151 
152  /// Retrieve the result type for a function pointer.
153  template<typename _Res, typename... _ArgTypes _GLIBCXX_NOEXCEPT_PARM>
154  struct _Weak_result_type_impl<_Res(*)(_ArgTypes...) _GLIBCXX_NOEXCEPT_QUAL>
155  { typedef _Res result_type; };
156 
157  /// Retrieve the result type for a varargs function pointer.
158  template<typename _Res, typename... _ArgTypes _GLIBCXX_NOEXCEPT_PARM>
159  struct
160  _Weak_result_type_impl<_Res(*)(_ArgTypes..., ...) _GLIBCXX_NOEXCEPT_QUAL>
161  { typedef _Res result_type; };
162 
163  // Let _Weak_result_type_impl perform the real work.
164  template<typename _Functor,
165  bool = is_member_function_pointer<_Functor>::value>
166  struct _Weak_result_type_memfun
167  : _Weak_result_type_impl<_Functor>
168  { };
169 
170  // A pointer to member function has a weak result type.
171  template<typename _MemFunPtr>
172  struct _Weak_result_type_memfun<_MemFunPtr, true>
173  {
174  using result_type = typename _Mem_fn_traits<_MemFunPtr>::__result_type;
175  };
176 
177  // A pointer to data member doesn't have a weak result type.
178  template<typename _Func, typename _Class>
179  struct _Weak_result_type_memfun<_Func _Class::*, false>
180  { };
181 
182  /**
183  * Strip top-level cv-qualifiers from the function object and let
184  * _Weak_result_type_memfun perform the real work.
185  */
186  template<typename _Functor>
187  struct _Weak_result_type
188  : _Weak_result_type_memfun<typename remove_cv<_Functor>::type>
189  { };
190 
191 #if __cplusplus <= 201703L
192  // Detect nested argument_type.
193  template<typename _Tp, typename = __void_t<>>
194  struct _Refwrap_base_arg1
195  { };
196 
197  // Nested argument_type.
198  template<typename _Tp>
199  struct _Refwrap_base_arg1<_Tp,
200  __void_t<typename _Tp::argument_type>>
201  {
202  typedef typename _Tp::argument_type argument_type;
203  };
204 
205  // Detect nested first_argument_type and second_argument_type.
206  template<typename _Tp, typename = __void_t<>>
207  struct _Refwrap_base_arg2
208  { };
209 
210  // Nested first_argument_type and second_argument_type.
211  template<typename _Tp>
212  struct _Refwrap_base_arg2<_Tp,
213  __void_t<typename _Tp::first_argument_type,
214  typename _Tp::second_argument_type>>
215  {
216  typedef typename _Tp::first_argument_type first_argument_type;
217  typedef typename _Tp::second_argument_type second_argument_type;
218  };
219 
220  /**
221  * Derives from unary_function or binary_function when it
222  * can. Specializations handle all of the easy cases. The primary
223  * template determines what to do with a class type, which may
224  * derive from both unary_function and binary_function.
225  */
226  template<typename _Tp>
227  struct _Reference_wrapper_base
228  : _Weak_result_type<_Tp>, _Refwrap_base_arg1<_Tp>, _Refwrap_base_arg2<_Tp>
229  { };
230 
231 // Ignore warnings about unary_function and binary_function.
232 #pragma GCC diagnostic push
233 #pragma GCC diagnostic ignored "-Wdeprecated-declarations"
234 
235  // - a function type (unary)
236  template<typename _Res, typename _T1 _GLIBCXX_NOEXCEPT_PARM>
237  struct _Reference_wrapper_base<_Res(_T1) _GLIBCXX_NOEXCEPT_QUAL>
238  : unary_function<_T1, _Res>
239  { };
240 
241  template<typename _Res, typename _T1>
242  struct _Reference_wrapper_base<_Res(_T1) const>
243  : unary_function<_T1, _Res>
244  { };
245 
246  template<typename _Res, typename _T1>
247  struct _Reference_wrapper_base<_Res(_T1) volatile>
248  : unary_function<_T1, _Res>
249  { };
250 
251  template<typename _Res, typename _T1>
252  struct _Reference_wrapper_base<_Res(_T1) const volatile>
253  : unary_function<_T1, _Res>
254  { };
255 
256  // - a function type (binary)
257  template<typename _Res, typename _T1, typename _T2 _GLIBCXX_NOEXCEPT_PARM>
258  struct _Reference_wrapper_base<_Res(_T1, _T2) _GLIBCXX_NOEXCEPT_QUAL>
259  : binary_function<_T1, _T2, _Res>
260  { };
261 
262  template<typename _Res, typename _T1, typename _T2>
263  struct _Reference_wrapper_base<_Res(_T1, _T2) const>
264  : binary_function<_T1, _T2, _Res>
265  { };
266 
267  template<typename _Res, typename _T1, typename _T2>
268  struct _Reference_wrapper_base<_Res(_T1, _T2) volatile>
269  : binary_function<_T1, _T2, _Res>
270  { };
271 
272  template<typename _Res, typename _T1, typename _T2>
273  struct _Reference_wrapper_base<_Res(_T1, _T2) const volatile>
274  : binary_function<_T1, _T2, _Res>
275  { };
276 
277  // - a function pointer type (unary)
278  template<typename _Res, typename _T1 _GLIBCXX_NOEXCEPT_PARM>
279  struct _Reference_wrapper_base<_Res(*)(_T1) _GLIBCXX_NOEXCEPT_QUAL>
280  : unary_function<_T1, _Res>
281  { };
282 
283  // - a function pointer type (binary)
284  template<typename _Res, typename _T1, typename _T2 _GLIBCXX_NOEXCEPT_PARM>
285  struct _Reference_wrapper_base<_Res(*)(_T1, _T2) _GLIBCXX_NOEXCEPT_QUAL>
286  : binary_function<_T1, _T2, _Res>
287  { };
288 
289  template<typename _Tp, bool = is_member_function_pointer<_Tp>::value>
290  struct _Reference_wrapper_base_memfun
291  : _Reference_wrapper_base<_Tp>
292  { };
293 
294  template<typename _MemFunPtr>
295  struct _Reference_wrapper_base_memfun<_MemFunPtr, true>
296  : _Mem_fn_traits<_MemFunPtr>::__maybe_type
297  {
298  using result_type = typename _Mem_fn_traits<_MemFunPtr>::__result_type;
299  };
300 #pragma GCC diagnostic pop
301 #endif // ! C++20
302 
303  /// @endcond
304 
305  /**
306  * @brief Primary class template for reference_wrapper.
307  * @ingroup functors
308  */
309  template<typename _Tp>
311 #if __cplusplus <= 201703L
312  // In C++20 std::reference_wrapper<T> allows T to be incomplete,
313  // so checking for nested types could result in ODR violations.
314  : public _Reference_wrapper_base_memfun<typename remove_cv<_Tp>::type>
315 #endif
316  {
317  _Tp* _M_data;
318 
319  _GLIBCXX20_CONSTEXPR
320  static _Tp* _S_fun(_Tp& __r) noexcept { return std::__addressof(__r); }
321 
322  static void _S_fun(_Tp&&) = delete;
323 
324  template<typename _Up, typename _Up2 = __remove_cvref_t<_Up>>
325  using __not_same
327 
328  public:
329  typedef _Tp type;
330 
331  // _GLIBCXX_RESOLVE_LIB_DEFECTS
332  // 2993. reference_wrapper<T> conversion from T&&
333  // 3041. Unnecessary decay in reference_wrapper
334  template<typename _Up, typename = __not_same<_Up>, typename
335  = decltype(reference_wrapper::_S_fun(std::declval<_Up>()))>
336  _GLIBCXX20_CONSTEXPR
337  reference_wrapper(_Up&& __uref)
338  noexcept(noexcept(reference_wrapper::_S_fun(std::declval<_Up>())))
339  : _M_data(reference_wrapper::_S_fun(std::forward<_Up>(__uref)))
340  { }
341 
342  reference_wrapper(const reference_wrapper&) = default;
343 
345  operator=(const reference_wrapper&) = default;
346 
347  _GLIBCXX20_CONSTEXPR
348  operator _Tp&() const noexcept
349  { return this->get(); }
350 
351  _GLIBCXX20_CONSTEXPR
352  _Tp&
353  get() const noexcept
354  { return *_M_data; }
355 
356  template<typename... _Args>
357  _GLIBCXX20_CONSTEXPR
358  typename __invoke_result<_Tp&, _Args...>::type
359  operator()(_Args&&... __args) const
360  noexcept(__is_nothrow_invocable<_Tp&, _Args...>::value)
361  {
362 #if __cplusplus > 201703L
363  if constexpr (is_object_v<type>)
364  static_assert(sizeof(type), "type must be complete");
365 #endif
366  return std::__invoke(get(), std::forward<_Args>(__args)...);
367  }
368 
369 #if __glibcxx_reference_wrapper >= 202403L // >= C++26
370  // [refwrap.comparisons], comparisons
371  [[nodiscard]]
372  friend constexpr bool
373  operator==(reference_wrapper __x, reference_wrapper __y)
374  requires requires { { __x.get() == __y.get() } -> convertible_to<bool>; }
375  { return __x.get() == __y.get(); }
376 
377  [[nodiscard]]
378  friend constexpr bool
379  operator==(reference_wrapper __x, const _Tp& __y)
380  requires requires { { __x.get() == __y } -> convertible_to<bool>; }
381  { return __x.get() == __y; }
382 
383  [[nodiscard]]
384  friend constexpr bool
386  requires (!is_const_v<_Tp>)
387  && requires { { __x.get() == __y.get() } -> convertible_to<bool>; }
388  { return __x.get() == __y.get(); }
389 
390  // _GLIBCXX_RESOLVE_LIB_DEFECTS
391  // 4071. reference_wrapper comparisons are not SFINAE-friendly
392 
393  [[nodiscard]]
394  friend constexpr auto
395  operator<=>(reference_wrapper __x, reference_wrapper __y)
396  requires requires (const _Tp __t) {
397  { __t < __t } -> __detail::__boolean_testable;
398  }
399  { return __detail::__synth3way(__x.get(), __y.get()); }
400 
401  [[nodiscard]]
402  friend constexpr auto
403  operator<=>(reference_wrapper __x, const _Tp& __y)
404  requires requires { { __y < __y } -> __detail::__boolean_testable; }
405  { return __detail::__synth3way(__x.get(), __y); }
406 
407  [[nodiscard]]
408  friend constexpr auto
409  operator<=>(reference_wrapper __x, reference_wrapper<const _Tp> __y)
410  requires (!is_const_v<_Tp>) && requires (const _Tp __t) {
411  { __t < __t } -> __detail::__boolean_testable;
412  }
413  { return __detail::__synth3way(__x.get(), __y.get()); }
414 #endif
415  };
416 
417 #if __cpp_deduction_guides
418  template<typename _Tp>
420 #endif
421 
422  /// @relates reference_wrapper @{
423 
424  /// Denotes a reference should be taken to a variable.
425  template<typename _Tp>
426  _GLIBCXX20_CONSTEXPR
428  ref(_Tp& __t) noexcept
429  { return reference_wrapper<_Tp>(__t); }
430 
431  /// Denotes a const reference should be taken to a variable.
432  template<typename _Tp>
433  _GLIBCXX20_CONSTEXPR
435  cref(const _Tp& __t) noexcept
436  { return reference_wrapper<const _Tp>(__t); }
437 
438  template<typename _Tp>
439  void ref(const _Tp&&) = delete;
440 
441  template<typename _Tp>
442  void cref(const _Tp&&) = delete;
443 
444  /// std::ref overload to prevent wrapping a reference_wrapper
445  template<typename _Tp>
446  _GLIBCXX20_CONSTEXPR
449  { return __t; }
450 
451  /// std::cref overload to prevent wrapping a reference_wrapper
452  template<typename _Tp>
453  _GLIBCXX20_CONSTEXPR
456  { return { __t.get() }; }
457 
458  /// @}
459 
460 _GLIBCXX_END_NAMESPACE_VERSION
461 } // namespace std
462 
463 #endif // C++11
464 
465 #endif // _GLIBCXX_REFWRAP_H
__bool_constant< true > true_type
The type used as a compile-time boolean with true value.
Definition: type_traits:116
__bool_constant< false > false_type
The type used as a compile-time boolean with false value.
Definition: type_traits:119
constexpr _Tp * __addressof(_Tp &__r) noexcept
Same as C++11 std::addressof.
Definition: move.h:52
constexpr __invoke_result< _Callable, _Args... >::type __invoke(_Callable &&__fn, _Args &&... __args) noexcept(__is_nothrow_invocable< _Callable, _Args... >::value)
Invoke a callable object.
Definition: invoke.h:92
ISO C++ entities toplevel namespace is std.
Primary class template for reference_wrapper.
Definition: refwrap.h:316
constexpr reference_wrapper< _Tp > ref(_Tp &__t) noexcept
Definition: refwrap.h:428
constexpr reference_wrapper< _Tp > ref(reference_wrapper< _Tp > __t) noexcept
std::ref overload to prevent wrapping a reference_wrapper
Definition: refwrap.h:448
constexpr reference_wrapper< const _Tp > cref(const _Tp &__t) noexcept
Denotes a const reference should be taken to a variable.
Definition: refwrap.h:435
constexpr reference_wrapper< const _Tp > cref(reference_wrapper< _Tp > __t) noexcept
std::cref overload to prevent wrapping a reference_wrapper
Definition: refwrap.h:455
Define a member typedef type only if a boolean constant is true.
Definition: type_traits:134