std::ranges::uninitialized_move, std::ranges::uninitialized_move_result

From cppreference.com
< cpp‎ | memory
 
C++
 
Memory management library
(exposition only*)
Uninitialized memory algorithms
(C++17)
(C++17)
(C++17)
(C++17)
(C++17)
(C++11)
(C++17)
(C++17)
(C++17)
(C++17)
(C++20)
Constrained uninitialized
memory algorithms
(C++20)
(C++20)
ranges::uninitialized_move
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20)
(C++20) 
(C++20)
C Library

Allocators
(C++11)
(C++23)
(C++11)
(C++11)
(C++20)
(C++20)
(C++20) 
(C++11)
(C++17)
Memory resources
(C++17)
(C++17)
(C++17)
(C++17)
(C++17)
(C++17)
(C++17)
(C++17)
(C++17)
Garbage collection support
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)
(C++11)(until C++23)
Uninitialized storage
(until C++20*)
(until C++20*)
(until C++20*)
Explicit lifetime management
(C++23)(C++23)
 
Defined in header <memory>
Call signature
template< std::input_iterator I, std::sentinel_for<I> S1,

          no-throw-forward-iterator O, no-throw-sentinel-for<O> S2 >
    requires std::constructible_from<std::iter_value_t<O>,
                                     std::iter_rvalue_reference_t<I>>
uninitialized_move_result<I, O>

    uninitialized_move( I ifirst, S1 ilast, O ofirst, S2 olast );
 (1) (since C++20)
(constexpr since C++26)
template< ranges::input_range IR, no-throw-forward-range OR >

    requires std::constructible_from
                 <ranges::range_value_t<OR>,
                  ranges::range_rvalue_reference_t<IR>>
uninitialized_move_result<ranges::borrowed_iterator_t<IR>,
                          ranges::borrowed_iterator_t<OR>>

    uninitialized_move( IR&& in_range, OR&& out_range );
 (2) (since C++20)
(constexpr since C++26)
Helper types
template< class I, class O >
using uninitialized_move_result = ranges::in_out_result<I, O>;
 (3) (since C++20)

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

1) Copies N elements from [ifirst, ilast) (using move semantics if supported) to an uninitialized memory area [ofirst, olast) as if by

for (; ifirst != ilast && ofirst != olast; ++ofirst, (void)++ifirst)
    ::new (voidify(*ofirst))
        std::remove_reference_t<std::iter_reference_t<O>>(ranges::iter_move(ifirst));
return {std::move(ifirst), ofirst};

If an exception is thrown during the initialization then the objects that already constructed in [ofirst, olast) are destroyed in an unspecified order. Also, the objects in [ifirst, ilast) that were already moved, are left in a valid but unspecified state.
2) Equivalent to return ranges::uninitialized_move(ranges::begin(in_range), ranges::end(in_range),
                                  ranges::begin(out_range), ranges::end(out_range));.

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

Parameters

ifirst, ilast - iterator-sentinel pair denoting the input range of elements to move from
in_range - the input range of elements to move from
ofirst, olast - iterator-sentinel pair denoting the output range to initialize
out_range - the output range to initialize

Return value

As described above.

Complexity

Linear in 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_move, e.g. by using 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,2)

Possible implementation

struct uninitialized_move_fn
{
    template<std::input_iterator I, std::sentinel_for<I> S1,
             no-throw-forward-iterator O, no-throw-sentinel-for<O> S2>
        requires std::constructible_from<std::iter_value_t<O>,
                                         std::iter_rvalue_reference_t<I>>
    constexpr ranges::uninitialized_move_result<I, O>
        operator()(I ifirst, S1 ilast, O ofirst, S2 olast) const
    {
        using ValueType = std::remove_reference_t<std::iter_reference_t<O>>;
        O current{ofirst};
        try
        {
            for (; !(ifirst == ilast or current == olast); ++ifirst, ++current)
                ::new (static_cast<void*>(std::addressof(*current))))
                    ValueType(ranges::iter_move(ifirst));
            return {std::move(ifirst), std::move(current)};
        }
        catch (...) // rollback: destroy constructed elements
        {
            for (; ofirst != current; ++ofirst)
                ranges::destroy_at(std::addressof(*ofirst));
            throw;
        }
    }
 
    template<ranges::input_range IR, no-throw-forward-range OR>
        requires std::constructible_from<ranges::range_value_t<OR>,
                                         ranges::range_rvalue_reference_t<IR>>
    constexpr ranges::uninitialized_move_result<ranges::borrowed_iterator_t<IR>,
                                                ranges::borrowed_iterator_t<OR>>
        operator()(IR&& in_range, OR&& out_range) const
    {
        return (*this)(ranges::begin(in_range), ranges::end(in_range),
                       ranges::begin(out_range), ranges::end(out_range));
    }
};
 
inline constexpr uninitialized_move_fn uninitialized_move{};

Example

Run this code
#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[]{"Home", "World"};
    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::ranges::uninitialized_move(std::begin(in), std::end(in), first, last);
 
            print("after move, in: ", std::begin(in), std::end(in));
            print("after move, out: ", first, last);
 
            std::ranges::destroy(first, last);
        }
        catch (...)
        {
            std::cout << "Exception!\n";
        }
        std::free(out);
    }
}

Possible output: 

initially, in: "Home" "World"
after move, in: "" ""
after move, out: "Home" "World"

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

See also

(C++20)
 moves a number of objects to an uninitialized area of memory
(algorithm function object)
(C++17)
 moves a range of objects to an uninitialized area of memory
(function template)
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/memory/ranges/uninitialized_move&oldid=179709"