Skip to content

Search topics & cppreference

Search all study topics, concept maps, and 6,587 C++ and C reference pages.

std::ranges::uninitialized_copy_n, std::ranges::uninitialized_copy_n_result

Let N be ranges::min(count, ranges::distance(ofirst, olast)).

Memory management
  • C++11
  • C++20
  • C++26
2 min readView on cppreference
NotebookLM
Defined in header <memory>
Call signature
template< std::input_iterator I,
          no-throw-input-iterator O, no-throw-sentinel-for<O> S >
    requires std::constructible_from<std::iter_value_t<O>,
                                     std::iter_reference_t<I>>
uninitialized_copy_n_result<I, O>
    uninitialized_copy_n( I ifirst, std::iter_difference_t<I> count,
                          O ofirst, S olast );
(1) (since C++20)
(constexpr since C++26)
Helper types
template< class I, class O >
using uninitialized_copy_n_result = ranges::in_out_result<I, O>;
(2) (since C++20)

Let N be ranges::min(count, ranges::distance(ofirst, olast)).

Copies N elements from the range beginning at ifirst to an uninitialized memory area [ofirst, olast) as if by auto ret = ranges::uninitialized_copy(std::counted_iterator(std::move(ifirst), count),
                                      std::default_sentinel, ofirst, olast);
return {std::move(ret.in).base(), ret.out};

If an exception is thrown during the initialization, the objects already constructed are destroyed in an unspecified order.

If [ofirst, olast) overlaps with ifirst + [​0​, count), the behavior is undefined.

The function-like entities described on this page are algorithm function objects (informally known as niebloids), that is:

Parameters

ifirst - the beginning of the range of elements to copy from
count - the number of elements to copy
ofirst, olast - iterator-sentinel pair denoting the destination range

Return value

As described above.

Complexity

𝓞(N).

Exceptions

Any exception thrown on construction of the elements in the destination range.

Notes

An implementation may improve the efficiency of the ranges::uninitialized_copy_n, by using e.g. ranges::copy_n, if the value type of the output range is TrivialType.

Feature-test macro Value Std Feature
__cpp_lib_raw_memory_algorithms 202411L (C++26) constexpr for specialized memory algorithms, (1)

Possible implementation

snippet.cpp
struct uninitialized_copy_n_fn
{
    template<std::input_iterator I, no-throw-input-iterator O, no-throw-sentinel-for<O> S>
        requires std::constructible_from<std::iter_value_t<O>, std::iter_reference_t<I>>
    constexpr ranges::uninitialized_copy_n_result<I, O>
        operator()(I ifirst, std::iter_difference_t<I> count, O ofirst, S olast) const
    {
        auto iter = std::counted_iterator(std::move(ifirst), count);
        auto ret = ranges::uninitialized_copy(iter, std::default_sentinel, ofirst, olast);
        return {std::move(ret.in).base(), ret.out};
    }
};
 
inline constexpr uninitialized_copy_n_fn uninitialized_copy_n{};

Example

example.cpp
#include <iomanip>
#include <iostream>
#include <memory>
#include <string>
 
int main()
{
    const char* stars[]{"Procyon", "Spica", "Pollux", "Deneb", "Polaris"};
 
    constexpr int n{4};
    alignas(alignof(std::string)) char out[n * sizeof(std::string)];
 
    try
    {
        auto first{reinterpret_cast<std::string*>(out)};
        auto last{first + n};
        auto ret{std::ranges::uninitialized_copy_n(std::begin(stars), n, first, last)};
 
        std::cout << '{';
        for (auto it{first}; it != ret.out; ++it)
            std::cout << (it == first ? "" : ", ") << std::quoted(*it);
        std::cout << "};\n";
 
        std::ranges::destroy(first, last);
    }
    catch (...)
    {
        std::cout << "uninitialized_copy_n exception\n";
    }
}
Output
{"Procyon", "Spica", "Pollux", "Deneb"};

See also

copies a range of objects to an uninitialized area of memory
(algorithm function object)
copies a number of objects to an uninitialized area of memory
(function template)

Content from this page on cppreference.com, licensed under CC-BY-SA 3.0 and GFDL. Modified: restyled, site navigation removed, code windows added. Offline snapshot of 9 February 2025.