std::uninitialized_move_n

Defined in header <memory>

Defined in header `<memory>`
template< class InputIt, class Size, class NoThrowForwardIt > std::pair<InputIt, NoThrowForwardIt> uninitialized_move_n( InputIt first, Size count, NoThrowForwardIt d_first );	(1)	(since C++17) (constexpr since C++26)
template< class ExecutionPolicy, class ForwardIt, class Size, class NoThrowForwardIt > std::pair<ForwardIt, NoThrowForwardIt> uninitialized_move_n( ExecutionPolicy&& policy, ForwardIt first, Size count, NoThrowForwardIt d_first );	(2)	(since C++17)

template< class InputIt, class Size, class NoThrowForwardIt >
std::pair<InputIt, NoThrowForwardIt>
    uninitialized_move_n( InputIt first, Size count,
                          NoThrowForwardIt d_first );

(1)

(since C++17)
(constexpr since C++26)

template< class ExecutionPolicy,
          class ForwardIt, class Size, class NoThrowForwardIt >
std::pair<ForwardIt, NoThrowForwardIt>
    uninitialized_move_n( ExecutionPolicy&& policy, ForwardIt first,
                          Size count, NoThrowForwardIt d_first );

(2)

(since C++17)

1) Constructs elements in the destination range beginning at d_first from the first count elements in the source range beginning at first as if by

for(;count>0;++d_first,(void)++first,--count) ::new(voidify(*d_first)) typenamestd::iterator_traits<NoThrowForwardIt>::value_type(deref-move(*iter)); return{first,d_first};

If an exception is thrown during the initialization, some objects in first + [0, count) are left in a valid but unspecified state, and the objects already constructed are destroyed in an unspecified order.

2) Same as (1), but executed according to policy.

This overload participates in overload resolution only if the value of the following expression is true:

`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)

If d_first + [0, count) overlaps with first + [0, count), the behavior is undefined.

(since C++20)

Parameters

first	-	the beginning of the range of the elements to move
d_first	-	the beginning of the destination range
count	-	the number of elements to move
policy	-	the execution policy to use
Type requirements
-`InputIt` must meet the requirements of LegacyInputIterator.
-`ForwardIt` must meet the requirements of LegacyForwardIterator.
-`NoThrowForwardIt` must meet the requirements of LegacyForwardIterator.
-No increment, assignment, comparison, or indirection through valid instances of `NoThrowForwardIt` may throw exceptions.

Return value

As described above.

Exceptions

2) During the execution process:

If the temporary memory resources required for parallelization are not available, std::bad_alloc is thrown.
If an uncaught exception is thrown while accessing objects via an algorithm argument, the behavior is determined by the execution policy (for standard policies, std::terminate is invoked).

Notes

When the input iterator deferences to an rvalue, the behavior of std::uninitialized_move_n is same as std::uninitialized_copy_n.

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

Possible implementation

template<class InputIt, class Size, class NoThrowForwardIt>
constexpr std::pair<InputIt, NoThrowForwardIt>
    uninitialized_move_n(InputIt first, Size count, NoThrowForwardIt d_first)
{
    using ValueType = typename std::iterator_traits<NoThrowForwardIt>::value_type;
    NoThrowForwardIt current = d_first;
    try
    {
        for (; count > 0; ++first, (void) ++current, --count) {
            auto addr = static_cast<void*>(std::addressof(*current));
            if constexpr (std::is_lvalue_reference_v<decltype(*first)>)
                ::new (addr) ValueType(std::move(*first));
            else
                ::new (addr) ValueType(*first);
        }
    }
    catch (...)
    {
        std::destroy(d_first, current);
        throw;
    }
    return {first, current};
}

Example

#include <cstdlib>
#include <iomanip>
#include <iostream>
#include <memory>
#include <string>

void print(auto rem, auto first, auto last)
{
    for (std::cout << rem; first != last; ++first)
        std::cout << std::quoted(*first) << ' ';
    std::cout << '\n';
}

int main()
{
    std::string in[]{"One", "Definition", "Rule"};
    print("initially, in: ", std::begin(in), std::end(in));
    
    if (constexpr auto sz = std::size(in);
        void* out = std::aligned_alloc(alignof(std::string), sizeof(std::string) * sz))
    {
        try
        {
            auto first{static_cast<std::string*>(out)};
            auto last{first + sz};
            std::uninitialized_move_n(std::begin(in), sz, first);
            
            print("after move, in: ", std::begin(in), std::end(in));
            print("after move, out: ", first, last);
            
            std::destroy(first, last);
        }
        catch (...)
        {
            std::cout << "Exception!\n";
        }
        std::free(out);
    }
}

Possible output:

initially, in: "One" "Definition" "Rule" 
after move, in: "" "" "" 
after move, out: "One" "Definition" "Rule"

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 3918	C++17	move constuction is always performed even if the input iterator deferences to a prvalue	no move construction in this case

uninitialized_move (C++17)	moves a range of objects to an uninitialized area of memory (function template & algorithm function object)
ranges::uninitialized_move (C++20)
uninitialized_copy_n (C++11)	copies a number of objects to an uninitialized area of memory (function template & algorithm function object)
ranges::uninitialized_copy_n (C++20)
ranges::uninitialized_move_n (C++20)	moves a number of objects to an uninitialized area of memory (algorithm function object)