libstdc++: refwrap.h Source File

libstdc++

refwrap.h
Go to the documentation of this file.
1// Implementation of std::reference_wrapper -*- C++ -*-
2
3// Copyright (C) 2004-2026 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
47namespace 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>
310 class reference_wrapper
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
326 = typename enable_if<!is_same<reference_wrapper, _Up2>::value>::type;
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
344 reference_wrapper&
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
385 operator==(reference_wrapper __x, reference_wrapper<const _Tp> __y)
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>
419 reference_wrapper(_Tp&) -> reference_wrapper<_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
427 inline reference_wrapper<_Tp>
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
434 inline reference_wrapper<const _Tp>
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
447 inline reference_wrapper<_Tp>
448 ref(reference_wrapper<_Tp> __t) noexcept
449 { return __t; }
450
451 /// std::cref overload to prevent wrapping a reference_wrapper
452 template<typename _Tp>
453 _GLIBCXX20_CONSTEXPR
454 inline reference_wrapper<const _Tp>
455 cref(reference_wrapper<_Tp> __t) noexcept
456 { return { __t.get() }; }
457
458 /// @}
459
460#if __glibcxx_common_reference_wrapper // C++ >= 20
461 namespace __detail
462 {
463 template<typename _Tp>
464 constexpr bool __is_ref_wrapper = false;
465
466 template<typename _Tp>
467 constexpr bool __is_ref_wrapper<reference_wrapper<_Tp>> = true;
468
469 template<typename _Rp, typename _Tp, typename _RQual, typename _TQual>
470 concept __ref_wrap_common_reference_exists_with = __is_ref_wrapper<_Rp>
471 && requires { typename common_reference_t<typename _Rp::type&, _TQual>; }
472 && convertible_to<_RQual, common_reference_t<typename _Rp::type&, _TQual>>;
473 } // namespace __detail
474
475 template<typename _Rp, typename _Tp,
476 template<typename> class _RQual, template<typename> class _TQual>
477 requires __detail::__ref_wrap_common_reference_exists_with<_Rp, _Tp,
478 _RQual<_Rp>, _TQual<_Tp>>
479 && (!__detail::__ref_wrap_common_reference_exists_with<_Tp, _Rp,
480 _TQual<_Tp>, _RQual<_Rp>>)
481 struct basic_common_reference<_Rp, _Tp, _RQual, _TQual>
482 { using type = common_reference_t<typename _Rp::type&, _TQual<_Tp>>; };
483
484 template<typename _Tp, typename _Rp,
485 template<typename> class _TQual, template<typename> class _RQual>
486 requires __detail::__ref_wrap_common_reference_exists_with<_Rp, _Tp,
487 _RQual<_Rp>, _TQual<_Tp>>
488 && (!__detail::__ref_wrap_common_reference_exists_with<_Tp, _Rp,
489 _TQual<_Tp>, _RQual<_Rp>>)
490 struct basic_common_reference<_Tp, _Rp, _TQual, _RQual>
491 { using type = common_reference_t<typename _Rp::type&, _TQual<_Tp>>; };
492#endif
493
494_GLIBCXX_END_NAMESPACE_VERSION
495} // namespace std
496
497#endif // C++11
498
499#endif // _GLIBCXX_REFWRAP_H
compare
invoke.h
move.h
stl_function.h
std::true_type
__bool_constant< true > true_type
The type used as a compile-time boolean with true value.
Definition type_traits:119
std::common_reference_t
typename common_reference< _Tp... >::type common_reference_t
Definition type_traits:4301
std::false_type
__bool_constant< false > false_type
The type used as a compile-time boolean with false value.
Definition type_traits:122
std::declval
auto declval() noexcept -> decltype(__declval< _Tp >(0))
Definition type_traits:2741
std::__invoke
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
std::__addressof
constexpr _Tp * __addressof(_Tp &__r) noexcept
Same as C++11 std::addressof.
Definition move.h:52
std::forward
constexpr _Tp && forward(typename std::remove_reference< _Tp >::type &__t) noexcept
Forward an lvalue.
Definition move.h:72
std
ISO C++ entities toplevel namespace is std.
std::__detail
Implementation details not part of the namespace std interface.
std::reference_wrapper
Primary class template for reference_wrapper.
Definition refwrap.h:316
std::reference_wrapper::ref
constexpr reference_wrapper< _Tp > ref(_Tp &__t) noexcept
Denotes a reference should be taken to a variable.
Definition refwrap.h:428
std::reference_wrapper::ref
constexpr reference_wrapper< _Tp > ref(reference_wrapper< _Tp > __t) noexcept
std::ref overload to prevent wrapping a reference_wrapper
Definition refwrap.h:448
std::reference_wrapper::cref
constexpr reference_wrapper< const _Tp > cref(const _Tp &__t) noexcept
Denotes a const reference should be taken to a variable.
Definition refwrap.h:435
std::reference_wrapper::cref
constexpr reference_wrapper< const _Tp > cref(reference_wrapper< _Tp > __t) noexcept
std::cref overload to prevent wrapping a reference_wrapper
Definition refwrap.h:455
std::enable_if
Define a member typedef type only if a boolean constant is true.
Definition type_traits:137
std::is_member_function_pointer
is_member_function_pointer
Definition type_traits:722
std::unary_function
Definition stl_function.h:121
std::binary_function
Definition stl_function.h:135
std::convertible_to
[concept.convertible], concept convertible_to
Definition concepts:81