std::uninitialized_default_construct_n
Defined in header <memory> |
||
---|---|---|
template< class ForwardIt, class Size > ForwardIt uninitialized_default_construct_n( ForwardIt first, Size n ); |
(1) | (since C++17) |
template< class ExecutionPolicy, class ForwardIt, class Size > ForwardIt uninitialized_default_construct_n( ExecutionPolicy&& policy, ForwardIt first, Size n ); |
(2) | (since C++17) |
1) Constructs
n
objects of type
typename iterator_traits<ForwardIt>::value_type
in the uninitialized storage starting at
first
by
default-initialization, as if by
for (; n > 0; (void) ++first, --n) ::new (/*VOIDIFY*/(*first)) typename std::iterator_traits<ForwardIt>::value_type;
where /*VOIDIFY*/(e)
is:
static_cast<void*>(std::addressof(e)) |
(until C++20) |
const_cast<void*>(static_cast<const volatile void*>(std::addressof(e))) |
(since C++20) |
If an exception is thrown during the initialization, the objects already constructed are destroyed in an unspecified order.
2) Same as
(1), but executed according to
policy
. This overload does not participate in overload resolution unless
std::is_execution_policy_v<std::decay_t<ExecutionPolicy>>
(until C++20)
std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>>
(since C++20) is true.
Parameters
first | - | the beginning of the range of elements to initialize |
n | - | the number of elements to construct |
policy | - | the execution policy to use. See execution policy for details. |
Type requirements | ||
-ForwardIt must meet the requirements of LegacyForwardIterator. |
||
-No increment, assignment, comparison, or indirection through valid instances of ForwardIt may throw exceptions. |
Return value
The end of the range of objects (i.e., std::next(first, n)
).
Complexity
Linear in n
.
Exceptions
The overload with a template parameter named ExecutionPolicy
reports errors as follows:
- If execution of a function invoked as part of the algorithm throws an exception and
ExecutionPolicy
is one of the standard policies,std::terminate
is called. For any otherExecutionPolicy
, the behavior is implementation-defined. - If the algorithm fails to allocate memory,
std::bad_alloc
is thrown.
Possible implementation
template<class ForwardIt, class Size> ForwardIt uninitialized_default_construct_n( ForwardIt first, Size n ) { using T = typename std::iterator_traits<ForwardIt>::value_type; ForwardIt current = first; try { for (; n > 0 ; (void) ++current, --n) { ::new (const_cast<void*>(static_cast<const volatile void*>( std::addressof(*current)))) T; } return current; } catch (...) { std::destroy(first, current); throw; } } |
Example
#include <iostream> #include <memory> #include <string> int main() { struct S { std::string m{ "Default value" }; }; constexpr int n {3}; alignas(alignof(S)) unsigned char mem[n * sizeof(S)]; try { auto first {reinterpret_cast<S*>(mem)}; auto last = std::uninitialized_default_construct_n(first, n); for (auto it {first}; it != last; ++it) { std::cout << it->m << '\n'; } std::destroy(first, last); } catch(...) { std::cout << "Exception!\n"; } // Notice that for "trivial types" the uninitialized_default_construct_n // generally does not zero-initialize the given uninitialized memory area. int v[] { 1, 2, 3, 4 }; const int original[] { 1, 2, 3, 4 }; std::uninitialized_default_construct_n(std::begin(v), std::size(v)); // for (const int i : v) { std::cout << i << ' '; } // Maybe undefined behavior, pending CWG 1997. std::cout << (std::memcmp(v, original, sizeof(v)) == 0 ? "Unmodified\n" : "Modified\n"); // The result is unspecified. }
Possible output:
Default value Default value Default value Unmodified
See also
(C++17)
|
constructs objects by default-initialization in an uninitialized area of memory, defined by a range (function template) |
(C++17)
|
constructs objects by value-initialization in an uninitialized area of memory, defined by a start and a count (function template) |
(C++20)
|
constructs objects by default-initialization in an uninitialized area of memory, defined by a start and count (niebloid) |
© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/memory/uninitialized_default_construct_n