libstdc++
utility
Go to the documentation of this file.
1 // <utility> -*- C++ -*-
2 
3 // Copyright (C) 2001-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 /*
26  *
27  * Copyright (c) 1994
28  * Hewlett-Packard Company
29  *
30  * Permission to use, copy, modify, distribute and sell this software
31  * and its documentation for any purpose is hereby granted without fee,
32  * provided that the above copyright notice appear in all copies and
33  * that both that copyright notice and this permission notice appear
34  * in supporting documentation. Hewlett-Packard Company makes no
35  * representations about the suitability of this software for any
36  * purpose. It is provided "as is" without express or implied warranty.
37  *
38  *
39  * Copyright (c) 1996,1997
40  * Silicon Graphics Computer Systems, Inc.
41  *
42  * Permission to use, copy, modify, distribute and sell this software
43  * and its documentation for any purpose is hereby granted without fee,
44  * provided that the above copyright notice appear in all copies and
45  * that both that copyright notice and this permission notice appear
46  * in supporting documentation. Silicon Graphics makes no
47  * representations about the suitability of this software for any
48  * purpose. It is provided "as is" without express or implied warranty.
49  */
50 
51 /** @file include/utility
52  * This is a Standard C++ Library header.
53  */
54 
55 #ifndef _GLIBCXX_UTILITY
56 #define _GLIBCXX_UTILITY 1
57 
58 #ifdef _GLIBCXX_SYSHDR
59 #pragma GCC system_header
60 #endif
61 
62 /**
63  * @defgroup utilities Utilities
64  *
65  * Basic function and class templates used with the rest of the library.
66  * Includes pair, swap, forward/move helpers, declval, integer_sequence.
67  */
68 
69 #include <bits/c++config.h>
70 #include <bits/stl_relops.h>
71 #include <bits/stl_pair.h>
72 
73 #if __cplusplus >= 201103L
74 
75 #include <initializer_list>
76 #include <type_traits>
77 #include <bits/move.h>
78 #include <bits/utility.h>
79 
80 #if __cplusplus >= 202002L
81 #include <ext/numeric_traits.h> // __is_standard_integer, __int_traits
82 #endif
83 
84 #if __cplusplus > 202302L
85 # include <bits/monostate.h>
86 #endif
87 
88 #define __glibcxx_want_addressof_constexpr
89 #define __glibcxx_want_as_const
90 #define __glibcxx_want_constexpr_algorithms
91 #define __glibcxx_want_constexpr_utility
92 #define __glibcxx_want_exchange_function
93 #define __glibcxx_want_forward_like
94 #define __glibcxx_want_integer_comparison_functions
95 #define __glibcxx_want_integer_sequence
96 #define __glibcxx_want_ranges_zip
97 #define __glibcxx_want_to_underlying
98 #define __glibcxx_want_tuple_element_t
99 #define __glibcxx_want_tuples_by_type
100 #define __glibcxx_want_unreachable
101 #define __glibcxx_want_tuple_like
102 #define __glibcxx_want_constrained_equality
103 #include <bits/version.h>
104 
105 namespace std _GLIBCXX_VISIBILITY(default)
106 {
107 _GLIBCXX_BEGIN_NAMESPACE_VERSION
108 
109 #ifdef __cpp_lib_exchange_function // C++ >= 14
110  /// Assign @p __new_val to @p __obj and return its previous value.
111  template <typename _Tp, typename _Up = _Tp>
112  _GLIBCXX20_CONSTEXPR
113  inline _Tp
114  exchange(_Tp& __obj, _Up&& __new_val)
115  noexcept(__and_<is_nothrow_move_constructible<_Tp>,
116  is_nothrow_assignable<_Tp&, _Up>>::value)
117  { return std::__exchange(__obj, std::forward<_Up>(__new_val)); }
118 #endif
119 
120 #ifdef __cpp_lib_as_const // C++ >= 17
121  template<typename _Tp>
122  [[nodiscard]]
123  constexpr add_const_t<_Tp>&
124  as_const(_Tp& __t) noexcept
125  { return __t; }
126 
127  template<typename _Tp>
128  void as_const(const _Tp&&) = delete;
129 #endif
130 
131 #ifdef __cpp_lib_integer_comparison_functions // C++ >= 20
132  template<typename _Tp, typename _Up>
133  constexpr bool
134  cmp_equal(_Tp __t, _Up __u) noexcept
135  {
136  static_assert(__is_standard_integer<_Tp>::value);
137  static_assert(__is_standard_integer<_Up>::value);
138 
139  if constexpr (is_signed_v<_Tp> == is_signed_v<_Up>)
140  return __t == __u;
141  else if constexpr (is_signed_v<_Tp>)
142  return __t >= 0 && make_unsigned_t<_Tp>(__t) == __u;
143  else
144  return __u >= 0 && __t == make_unsigned_t<_Up>(__u);
145  }
146 
147  template<typename _Tp, typename _Up>
148  constexpr bool
149  cmp_not_equal(_Tp __t, _Up __u) noexcept
150  { return !std::cmp_equal(__t, __u); }
151 
152  template<typename _Tp, typename _Up>
153  constexpr bool
154  cmp_less(_Tp __t, _Up __u) noexcept
155  {
156  static_assert(__is_standard_integer<_Tp>::value);
157  static_assert(__is_standard_integer<_Up>::value);
158 
159  if constexpr (is_signed_v<_Tp> == is_signed_v<_Up>)
160  return __t < __u;
161  else if constexpr (is_signed_v<_Tp>)
162  return __t < 0 || make_unsigned_t<_Tp>(__t) < __u;
163  else
164  return __u >= 0 && __t < make_unsigned_t<_Up>(__u);
165  }
166 
167  template<typename _Tp, typename _Up>
168  constexpr bool
169  cmp_greater(_Tp __t, _Up __u) noexcept
170  { return std::cmp_less(__u, __t); }
171 
172  template<typename _Tp, typename _Up>
173  constexpr bool
174  cmp_less_equal(_Tp __t, _Up __u) noexcept
175  { return !std::cmp_less(__u, __t); }
176 
177  template<typename _Tp, typename _Up>
178  constexpr bool
179  cmp_greater_equal(_Tp __t, _Up __u) noexcept
180  { return !std::cmp_less(__t, __u); }
181 
182  template<typename _Res, typename _Tp>
183  constexpr bool
184  in_range(_Tp __t) noexcept
185  {
186  static_assert(__is_standard_integer<_Res>::value);
187  static_assert(__is_standard_integer<_Tp>::value);
188  using __gnu_cxx::__int_traits;
189 
190  if constexpr (is_signed_v<_Tp> == is_signed_v<_Res>)
191  return __int_traits<_Res>::__min <= __t
192  && __t <= __int_traits<_Res>::__max;
193  else if constexpr (is_signed_v<_Tp>)
194  return __t >= 0
195  && make_unsigned_t<_Tp>(__t) <= __int_traits<_Res>::__max;
196  else
197  return __t <= make_unsigned_t<_Res>(__int_traits<_Res>::__max);
198  }
199 #endif // __cpp_lib_integer_comparison_functions
200 
201 #ifdef __cpp_lib_to_underlying // C++ >= 23
202  /// Convert an object of enumeration type to its underlying type.
203  template<typename _Tp>
204  [[nodiscard]]
205  constexpr underlying_type_t<_Tp>
206  to_underlying(_Tp __value) noexcept
207  { return static_cast<underlying_type_t<_Tp>>(__value); }
208 #endif
209 
210 #ifdef __cpp_lib_unreachable // C++ >= 23
211  /// Informs the compiler that program control flow never reaches this point.
212  /**
213  * Evaluating a call to this function results in undefined behaviour.
214  * This can be used as an assertion informing the compiler that certain
215  * conditions are impossible, for when the compiler is unable to determine
216  * that by itself.
217  *
218  * For example, it can be used to prevent warnings about reaching the
219  * end of a non-void function without returning.
220  *
221  * @since C++23
222  */
223  [[noreturn,__gnu__::__always_inline__]]
224  inline void
225  unreachable()
226  {
227 #ifdef _GLIBCXX_DEBUG
228  std::__glibcxx_assert_fail(nullptr, 0, "std::unreachable()", nullptr);
229 #elif defined _GLIBCXX_ASSERTIONS
230  __builtin_trap();
231 #else
232  __builtin_unreachable();
233 #endif
234  }
235 #endif
236 
237 _GLIBCXX_END_NAMESPACE_VERSION
238 } // namespace
239 
240 #endif
241 
242 #endif /* _GLIBCXX_UTILITY */