libstdc++-v3/include/bits/stl_construct.h

   1 // nonstandard construct and destroy functions -*- 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 bits/stl_construct.h
  52  *  This is an internal header file, included by other library headers.
  53  *  Do not attempt to use it directly. @headername{memory}
  54  */
  55
  56 #ifndef _STL_CONSTRUCT_H
  57 #define _STL_CONSTRUCT_H 1
  58
  59 #include <new>
  60 #include <bits/move.h>
  61 #include <bits/stl_iterator_base_types.h> // for iterator_traits
  62 #include <bits/stl_iterator_base_funcs.h> // for advance
  63
  64 /* This file provides the C++17 functions std::destroy_at, std::destroy, and
  65  * std::destroy_n, and the C++20 function std::construct_at.
  66  * It also provides std::_Construct, std::_Destroy,and std::_Destroy_n functions
  67  * which are defined in all standard modes and so can be used in C++98-14 code.
  68  * The _Destroy functions will dispatch to destroy_at during constant
  69  * evaluation, because calls to that function are intercepted by the compiler
  70  * to allow use in constant expressions.
  71  */
  72
  73 namespace std _GLIBCXX_VISIBILITY(default)
  74 {
  75 _GLIBCXX_BEGIN_NAMESPACE_VERSION
  76
  77 #if __glibcxx_raw_memory_algorithms // >= C++17
  78   template <typename _Tp>
  79     _GLIBCXX20_CONSTEXPR inline void
  80     destroy_at(_Tp* __location)
  81     {
  82       if constexpr (__cplusplus > 201703L && is_array_v<_Tp>)
  83         {
  84           for (auto& __x : *__location)
  85             std::destroy_at(std::addressof(__x));
  86         }
  87       else
  88         __location->~_Tp();
  89     }
  90
  91 #if __cpp_constexpr_dynamic_alloc // >= C++20
  92   template<typename _Tp, typename... _Args>
  93     requires (!is_unbounded_array_v<_Tp>)
  94       && requires { ::new((void*)0) _Tp(std::declval<_Args>()...); }
  95     constexpr _Tp*
  96     construct_at(_Tp* __location, _Args&&... __args)
  97     noexcept(noexcept(::new((void*)0) _Tp(std::declval<_Args>()...)))
  98     {
  99       void* __loc = __location;
 100       // _GLIBCXX_RESOLVE_LIB_DEFECTS
 101       // 3436. std::construct_at should support arrays
 102       if constexpr (is_array_v<_Tp>)
 103         {
 104           static_assert(sizeof...(_Args) == 0, "std::construct_at for array "
 105                        "types must not use any arguments to initialize the "
 106                        "array");
 107           return ::new(__loc) _Tp[1]();
 108         }
 109       else
 110         return ::new(__loc) _Tp(std::forward<_Args>(__args)...);
 111     }
 112 #endif // C++20
 113 #endif// C++17
 114
 115   /**
 116    * Constructs an object in existing memory by invoking an allocated
 117    * object's constructor with an initializer.
 118    */
 119 #if __cplusplus >= 201103L
 120   template<typename _Tp, typename... _Args>
 121     _GLIBCXX20_CONSTEXPR
 122     inline void
 123     _Construct(_Tp* __p, _Args&&... __args)
 124     {
 125 #if __cpp_constexpr_dynamic_alloc // >= C++20
 126       if (std::is_constant_evaluated())
 127         {
 128           // Allow std::_Construct to be used in constant expressions.
 129           std::construct_at(__p, std::forward<_Args>(__args)...);
 130           return;
 131         }
 132 #endif
 133       ::new(static_cast<void*>(__p)) _Tp(std::forward<_Args>(__args)...);
 134     }
 135 #else
 136   template<typename _T1, typename _T2>
 137     inline void
 138     _Construct(_T1* __p, const _T2& __value)
 139     {
 140       // _GLIBCXX_RESOLVE_LIB_DEFECTS
 141       // 402. wrong new expression in [some_]allocator::construct
 142       ::new(static_cast<void*>(__p)) _T1(__value);
 143     }
 144 #endif
 145
 146   template<typename _T1>
 147     _GLIBCXX26_CONSTEXPR
 148     inline void
 149     _Construct_novalue(_T1* __p)
 150     { ::new(static_cast<void*>(__p)) _T1; }
 151
 152   template<typename _ForwardIterator>
 153     _GLIBCXX20_CONSTEXPR void
 154     _Destroy(_ForwardIterator __first, _ForwardIterator __last);
 155
 156   /**
 157    * Destroy the object pointed to by a pointer type.
 158    */
 159   template<typename _Tp>
 160     _GLIBCXX14_CONSTEXPR inline void
 161     _Destroy(_Tp* __pointer)
 162     {
 163 #if __cpp_constexpr_dynamic_alloc // >= C++20
 164       std::destroy_at(__pointer);
 165 #else
 166       __pointer->~_Tp();
 167 #endif
 168     }
 169
 170 #pragma GCC diagnostic push
 171 #pragma GCC diagnostic ignored "-Wc++17-extensions" // for if-constexpr
 172
 173 #if __cplusplus < 201103L
 174   template<bool>
 175     struct _Destroy_aux
 176     {
 177       template<typename _ForwardIterator>
 178         static _GLIBCXX20_CONSTEXPR void
 179         __destroy(_ForwardIterator __first, _ForwardIterator __last)
 180         {
 181           for (; __first != __last; ++__first)
 182             std::_Destroy(std::__addressof(*__first));
 183         }
 184
 185       template<typename _ForwardIterator, typename _Size>
 186         static _GLIBCXX20_CONSTEXPR _ForwardIterator
 187         __destroy_n(_ForwardIterator __first, _Size __count)
 188         {
 189           for (; __count > 0; (void)++__first, --__count)
 190             std::_Destroy(std::__addressof(*__first));
 191           return __first;
 192         }
 193     };
 194
 195   template<>
 196     struct _Destroy_aux<true>
 197     {
 198       template<typename _ForwardIterator>
 199         static void
 200         __destroy(_ForwardIterator, _ForwardIterator) { }
 201
 202       template<typename _ForwardIterator, typename _Size>
 203         static _ForwardIterator
 204         __destroy_n(_ForwardIterator __first, _Size __count)
 205         {
 206           std::advance(__first, __count);
 207           return __first;
 208         }
 209     };
 210 #endif
 211
 212   /**
 213    * Destroy a range of objects.  If the value_type of the object has
 214    * a trivial destructor, the compiler should optimize all of this
 215    * away, otherwise the objects' destructors must be invoked.
 216    */
 217   template<typename _ForwardIterator>
 218     _GLIBCXX20_CONSTEXPR inline void
 219     _Destroy(_ForwardIterator __first, _ForwardIterator __last)
 220     {
 221       typedef typename iterator_traits<_ForwardIterator>::value_type
 222                        _Value_type;
 223 #if __cplusplus >= 201103L
 224       if constexpr (!is_trivially_destructible<_Value_type>::value)
 225         for (; __first != __last; ++__first)
 226           std::_Destroy(std::addressof(*__first));
 227 #if __cpp_constexpr_dynamic_alloc // >= C++20
 228       else if (std::is_constant_evaluated())
 229         for (; __first != __last; ++__first)
 230           std::destroy_at(std::addressof(*__first));
 231 #endif
 232 #else
 233       std::_Destroy_aux<__has_trivial_destructor(_Value_type)>::
 234         __destroy(__first, __last);
 235 #endif
 236     }
 237
 238   /**
 239    * Destroy a range of objects.  If the value_type of the object has
 240    * a trivial destructor, the compiler should optimize all of this
 241    * away, otherwise the objects' destructors must be invoked.
 242    */
 243   template<typename _ForwardIterator, typename _Size>
 244     _GLIBCXX20_CONSTEXPR inline _ForwardIterator
 245     _Destroy_n(_ForwardIterator __first, _Size __count)
 246     {
 247       typedef typename iterator_traits<_ForwardIterator>::value_type
 248                        _Value_type;
 249 #if __cplusplus >= 201103L
 250       if constexpr (!is_trivially_destructible<_Value_type>::value)
 251         for (; __count > 0; (void)++__first, --__count)
 252           std::_Destroy(std::addressof(*__first));
 253 #if __cpp_constexpr_dynamic_alloc // >= C++20
 254       else if (std::is_constant_evaluated())
 255         for (; __count > 0; (void)++__first, --__count)
 256           std::destroy_at(std::addressof(*__first));
 257 #endif
 258       else
 259         std::advance(__first, __count);
 260       return __first;
 261 #else
 262       return std::_Destroy_aux<__has_trivial_destructor(_Value_type)>::
 263         __destroy_n(__first, __count);
 264 #endif
 265     }
 266 #pragma GCC diagnostic pop
 267
 268 #if __glibcxx_raw_memory_algorithms // >= C++17
 269   template <typename _ForwardIterator>
 270     _GLIBCXX20_CONSTEXPR inline void
 271     destroy(_ForwardIterator __first, _ForwardIterator __last)
 272     {
 273       std::_Destroy(__first, __last);
 274     }
 275
 276   template <typename _ForwardIterator, typename _Size>
 277     _GLIBCXX20_CONSTEXPR inline _ForwardIterator
 278     destroy_n(_ForwardIterator __first, _Size __count)
 279     {
 280       return std::_Destroy_n(__first, __count);
 281     }
 282 #endif // C++17
 283
 284 _GLIBCXX_END_NAMESPACE_VERSION
 285 } // namespace std
 286
 287 #endif /* _STL_CONSTRUCT_H */