std::ranges::uninitialized_value_construct_n
Defined in header <memory> | ||
Call signature | ||
template<no-throw-forward-iterator I > requires std::default_initializable<std::iter_value_t<I>> | (since C++20) (constexpr since C++26) | |
Constructs objects of type std::iter_value_t<I> in the uninitialized memory area first + [0, count) by value-initialization, as if by returnranges::uninitialized_value_construct(std::counted_iterator(first, count),
std::default_sentinel).base();
If an exception is thrown during the initialization, the objects already constructed are destroyed in an unspecified order.
The function-like entities described on this page are algorithm function objects (informally known as niebloids), that is:
- Explicit template argument lists cannot be specified when calling any of them.
- None of them are visible to argument-dependent lookup.
- When any of them are found by normal unqualified lookup as the name to the left of the function-call operator, argument-dependent lookup is inhibited.
Contents |
[edit]Parameters
| first | - | the beginning of the range of elements to initialize |
| count | - | the number of elements to construct |
[edit]Return value
As described above.
[edit]Complexity
Linear in count.
[edit]Exceptions
Any exception thrown on construction of the elements in the destination range.
[edit]Notes
An implementation may improve the efficiency of the ranges::uninitialized_value_construct_n, e.g. by using ranges::fill_n, if the value type of the range is a CopyAssignableTrivialType.
| Feature-test macro | Value | Std | Feature |
|---|---|---|---|
__cpp_lib_raw_memory_algorithms | 202411L | (C++26) | constexpr for specialized memory algorithms |
[edit]Possible implementation
struct uninitialized_value_construct_n_fn {template<no-throw-forward-iterator I> requires std::default_initializable<std::iter_value_t<I>>constexpr I operator()(I first, std::iter_difference_t<I> count)const{auto iter =std::counted_iterator(first, count);returnranges::uninitialized_value_construct(iter, std::default_sentinel).base();}}; inlineconstexpr uninitialized_value_construct_n_fn uninitialized_value_construct_n{}; |
[edit]Example
#include <iostream>#include <memory>#include <string> int main(){struct S {std::string m{"█▓▒░ █▓▒░ █▓▒░ "};}; constexprint n{4}; alignas(alignof(S))char out[n * sizeof(S)]; try{auto first{reinterpret_cast<S*>(out)};auto last = std::ranges::uninitialized_value_construct_n(first, n); auto count{1};for(auto it{first}; it != last;++it)std::cout<< count++<<' '<< it->m <<'\n'; std::ranges::destroy(first, last);}catch(...){std::cout<<"Exception!\n";} // For scalar types, uninitialized_value_construct_n// zero-initializes the given uninitialized memory area.int v[]{1, 2, 3, 4, 5, 6, 7, 8};std::cout<<' ';for(constint i : v)std::cout<< i <<' ';std::cout<<"\n "; std::ranges::uninitialized_value_construct_n(std::begin(v), std::size(v));for(constint i : v)std::cout<< i <<' ';std::cout<<'\n';}
Output:
1 █▓▒░ █▓▒░ █▓▒░ 2 █▓▒░ █▓▒░ █▓▒░ 3 █▓▒░ █▓▒░ █▓▒░ 4 █▓▒░ █▓▒░ █▓▒░ 1 2 3 4 5 6 7 8 0 0 0 0 0 0 0 0
[edit]Defect reports
The following behavior-changing defect reports were applied retroactively to previously published C++ standards.
| DR | Applied to | Behavior as published | Correct behavior |
|---|---|---|---|
| LWG 3870 | C++20 | this algorithm might create objects on a const storage | kept disallowed |
[edit]See also
| constructs objects by value-initialization in an uninitialized area of memory, defined by a range (algorithm function object) | |
| constructs objects by default-initialization in an uninitialized area of memory, defined by a range (algorithm function object) | |
| constructs objects by default-initialization in an uninitialized area of memory, defined by a start and count (algorithm function object) | |
| constructs objects by value-initialization in an uninitialized area of memory, defined by a start and a count (function template) |
