std::ranges::uninitialized_copy, std::ranges::uninitialized_copy_result

 

C++

Compiler support

Freestanding and hosted

Language

Standard library headers

Named requirements

Feature test macros (C++20)

Language support library

Concepts library (C++20)

Metaprogramming library (C++11)

Diagnostics library

General utilities library

Strings library

Containers library

Iterators library

Ranges library (C++20)

Algorithms library

Numerics library

Localizations library

Input/output library

Filesystem library (C++17)

Regular expressions library (C++11)

Concurrency support library (C++11)

Technical specifications

Symbols index

External libraries

 

Utilities library

Language support Type support (basic types, RTTI) Library feature-test macros (C++20) Dynamic memory management Program utilities Coroutine support (C++20) Variadic functions is_constant_evaluated (C++20) launder (C++17) initializer_list (C++11) source_location (C++20) Three-way comparison (C++20) three_way_comparablethree_way_comparable_with (C++20)(C++20) strong_ordering (C++20) weak_ordering (C++20) partial_ordering (C++20) common_comparison_category (C++20) compare_three_way_result (C++20) compare_three_way (C++20) strong_order (C++20) weak_order (C++20) partial_order (C++20) compare_strong_order_fallback (C++20) compare_weak_order_fallback (C++20) compare_partial_order_fallback (C++20)    is_eqis_neqis_ltis_lteqis_gtis_gteq (C++20)(C++20)(C++20)(C++20)(C++20)(C++20)

General utilities Date and time Function objects Formatting library (C++20) bitset hash (C++11) Relational operators (deprecated in C++20) rel_ops::operator!=rel_ops::operator> rel_ops::operator<=rel_ops::operator>= Integer comparison functions cmp_equalcmp_lesscmp_less_than (C++20)(C++20)(C++20)    cmp_not_equalcmp_greatercmp_greater_than (C++20)(C++20)(C++20) in_range (C++20) Swap and type operations swap ranges::swap (C++20) exchange (C++14) declval (C++11) to_underlying (C++23) forward (C++11) forward_like (C++23) move (C++11) move_if_noexcept (C++11) as_const (C++17) Common vocabulary types pair tuple (C++11) optional (C++17) any (C++17) variant (C++17) tuple_size (C++11) tuple_element (C++11) apply (C++17) make_from_tuple (C++17) expected (C++23) Elementary string conversions to_chars (C++17) from_chars (C++17) chars_format (C++17)

 

Dynamic memory management

Smart pointers unique_ptr (C++11) shared_ptr (C++11) weak_ptr (C++11) auto_ptr (until C++17) owner_less (C++11) enable_shared_from_this (C++11) bad_weak_ptr (C++11) default_delete (C++11) out_ptr_t (C++23) inout_ptr_t (C++23) Allocators allocator allocator_traits (C++11) allocation_result (C++23) allocate_at_least (C++23) allocator_arg (C++11) uses_allocator (C++11) uses_allocator_construction_args (C++20) make_obj_using_allocator (C++20) uninitialized_construct_using_allocator (C++20) scoped_allocator_adaptor (C++11) pmr::polymorphic_allocator (C++17) Memory resources pmr::memory_resource (C++17) pmr::get_default_resource (C++17) pmr::set_default_resource (C++17) pmr::new_delete_resource (C++17) pmr::null_memory_resource (C++17) pmr::synchronized_pool_resource (C++17) pmr::unsynchronized_pool_resource (C++17) pmr::monotonic_buffer_resource (C++17) pmr::pool_options (C++17) Uninitialized storage raw_storage_iterator (until C++20) get_temporary_buffer (until C++20) return_temporary_buffer (until C++20)

Uninitialized memory algorithms uninitialized_copy uninitialized_fill uninitialized_move (C++17) uninitialized_default_construct (C++17) uninitialized_value_construct (C++17) destroy (C++17) destroy_at (C++17) uninitialized_copy_n (C++11) uninitialized_fill_n uninitialized_move_n (C++17) uninitialized_default_construct_n (C++17) uninitialized_value_construct_n (C++17) destroy_n (C++17) construct_at (C++20) Constrained uninitialized memory algorithms ranges::uninitialized_copy (C++20) ranges::uninitialized_fill (C++20) ranges::uninitialized_move (C++20) ranges::uninitialized_default_construct (C++20) ranges::uninitialized_value_construct (C++20) ranges::destroy (C++20) ranges::destroy_at (C++20) ranges::uninitialized_copy_n (C++20) ranges::uninitialized_fill_n (C++20) ranges::uninitialized_move_n (C++20) ranges::uninitialized_default_construct_n (C++20) ranges::uninitialized_value_construct_n (C++20) ranges::destroy_n (C++20) ranges::construct_at (C++20) Garbage collection support declare_reachable (C++11)(until C++23) undeclare_reachable (C++11)(until C++23) declare_no_pointers (C++11)(until C++23) undeclare_no_pointers (C++11)(until C++23) pointer_safety (C++11)(until C++23) get_pointer_safety (C++11)(until C++23) Miscellaneous pointer_traits (C++11) to_address (C++20) addressof (C++11) align (C++11) assume_aligned (C++20) C Library malloc aligned_alloc (C++17) calloc realloc free Low level memory management operator new operator new[] operator delete operator delete[] get_new_handler set_new_handler bad_alloc bad_array_new_length nothrow_t align_val_t destroying_delete_t new_handler nothrow

 

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_reference_t<I>>           uninitialized_copy_result<I, O>           uninitialized_copy( I ifirst, S1 ilast, O ofirst, S2 olast );	(1)	(since C++20)
template< ranges::input_range IR, no-throw-forward-range OR > requires  std::constructible_from<ranges::range_value_t<OR>,           ranges::range_reference_t<IR>>           uninitialized_copy_result<ranges::borrowed_iterator_t<IR>,                                     ranges::borrowed_iterator_t<OR>>           uninitialized_copy( IR&& in_range, OR&& out_range );	(2)	(since C++20)
Helper types
template<class I, class O> using uninitialized_copy_result = ranges::in_out_result<I, O>;	(3)	(since C++20)

1) Let \(\scriptsize N\)N be ranges::min(ranges::distance(ifirst, ilast), ranges::distance(ofirst, olast)), constructs \(\scriptsize N\)N elements in the output range [ofirst, olast), which is an uninitialized memory area, from the elements in the input range [ifirst, ilast).

The input and output ranges must not overlap.

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

The function has the effect equal to:

for (; !(ifirst == ilast || ofirst == olast); ++ofirst, ++ifirst) {
    ::new (const_cast<void*>(static_cast<const volatile void*>(std::addressof(*ofirst))))
        std::remove_reference_t<std::iter_reference_t<O>>(*ifirst);
}

2) Same as (1), but uses in_range as the first range and out_range as the second range, as if using ranges::begin(in_range) as ifirst, ranges::end(in_range) as ilast, ranges::begin(out_range) as ofirst, and ranges::end(out_range) as olast.

The function-like entities described on this page are niebloids, that is:

• Explicit template argument lists may not be specified when calling any of them.
• None of them is visible to argument-dependent lookup.
• When one of them is found by normal unqualified lookup for the name to the left of the function-call operator, it inhibits argument-dependent lookup.

In practice, they may be implemented as function objects, or with special compiler extensions.

Parameters

ifirst, ilast	-	iterator-sentinel pair denoting the range of elements to copy from
in_range	-	the range of elements to copy from
ofirst, olast	-	iterator-sentinel pair denoting the destination range
out_range	-	the destination range

Return value

{ifirst + N, ofirst + N}.

Complexity

\(\scriptsize\mathcal{O}(N)\)𝓞(N).

Exceptions

The exception thrown on construction of the elements in the destination range, if any.

Notes

An implementation may improve the efficiency of ranges::uninitialized_copy if the value type of the output range is TrivialType.

Possible implementation

struct uninitialized_copy_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_reference_t<I>> ranges::uninitialized_copy_result<I, O> operator()( I ifirst, S1 ilast, O ofirst, S2 olast ) const { O current {ofirst}; try { for (; !(ifirst == ilast or current == olast); ++ifirst, ++current) ranges::construct_at(std::addressof(*current), *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_reference_t<IR>> ranges::uninitialized_copy_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_copy_fn uninitialized_copy{};

Example

Run this code

#include <cstdlib>
#include <iomanip>
#include <iostream>
#include <memory>
#include <string>
 
int main()
{
    const char* v[] { "This", "is", "an", "example", };
 
    if (const auto sz{std::size(v)};
        void* pbuf = std::aligned_alloc(alignof(std::string), sizeof(std::string) * sz))
    {
        try
        {
            auto first {static_cast<std::string*>(pbuf)};
            auto last {first + sz};
            std::ranges::uninitialized_copy(std::begin(v), std::end(v), first, last);
 
            std::cout << "{ ";
            for (auto it {first}; it != last; ++it)
                std::cout << std::quoted(*it) << ", ";
            std::cout << "};\n";
 
            std::ranges::destroy(first, last);
        }
        catch(...)
        {
            std::cout << "uninitialized_copy exception\n";
        }
        std::free(pbuf);
    }
}

Output:

{ "This", "is", "an", "example", };

See also

ranges::uninitialized_copy_n (C++20)	copies a number of objects to an uninitialized area of memory (niebloid)
uninitialized_copy	copies a range of objects to an uninitialized area of memory (function template)