libstdc++-v3/include/std/utility

   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, __gnu__::__always_inline__]]
 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 */