View source for cpp/memory/uninitialized copy n

{{cpp/title|uninitialized_copy_n}}
{{cpp/memory/navbar}}
{{dcl begin}}
{{dcl header|memory}}
{{dcl|since=c++11|num=1|1= 
template< class InputIt, class Size, class NoThrowForwardIt >
NoThrowForwardIt uninitialized_copy_n( InputIt first, Size count,
                                       NoThrowForwardIt d_first );
}}
{{dcl|since=c++17|num=2|1=
template< class ExecutionPolicy, class ForwardIt,
          class Size, class NoThrowForwardIt >
NoThrowForwardIt uninitialized_copy_n( ExecutionPolicy&& policy,
                                       ForwardIt first, Size count,
                                       NoThrowForwardIt d_first );}}
{{dcl end}}
                                    
@1@ Copies {{c|count}} elements from a range beginning at {{c|first}} to an uninitialized memory area beginning at {{c|d_first}} as if by<br>
{{c multi|
for (; n > 0; ++d_first, (void) ++first, --n)|
     ::new (static_cast<void*>(std::addressof(*d_first)))|
        typename std::iterator_traits<NoThrowForwardIt>::value_type(*first);
}}

@@ If an exception is thrown during the initialization, the objects already constructed are destroyed in an unspecified order.
{{rrev|since=c++20|
If {{counted range|d_first|n}} overlaps with {{counted range|first|n}}, the behavior is undefined.
}}

@2@ Same as {{v|1}}, but executed according to {{c|policy}}. {{cpp/algorithm/parallel overload precondition}}

===Parameters===
{{par begin}}
{{par|first|the beginning of the range of the elements to copy}}
{{par|count|the number of elements to copy}}
{{par|d_first|the beginning of the destination range}}
{{par exec pol}}
{{par hreq}}
{{par req named|InputIt|InputIterator}}
{{par req named|ForwardIt|ForwardIterator}}
{{par req named|NoThrowForwardIt|ForwardIterator}}
{{par req|No increment, assignment, comparison, or indirection through valid instances of {{tt|NoThrowForwardIt}} may throw exceptions.}}
{{par end}}

===Return value===
Iterator to the element past the last element copied.

===Complexity===
Linear in {{c|count}}.

===Exceptions===
{{cpp/algorithm/parallel_exceptions_reporting_behavior|singular=yes}}

===Possible implementation===
{{eq fun|1=
template<class InputIt, class Size, class NoThrowForwardIt>
NoThrowForwardIt uninitialized_copy_n(InputIt first, Size count, NoThrowForwardIt d_first)
{
    using T = typename std::iterator_traits<NoThrowForwardIt>::value_type;
    NoThrowForwardIt current = d_first;
    try
    {
        for (; count > 0; ++first, (void) ++current, --count)
            ::new (static_cast<void*>(std::addressof(*current))) T(*first);
    }
    catch (...)
    {
        for (; d_first != current; ++d_first)
            d_first->~T();
        throw;
    }
    return current;
}
}}

===Example===
{{example
|code=
#include <algorithm>
#include <iostream>
#include <memory>
#include <string>
#include <tuple>
#include <vector>

int main()
{
    std::vector<std::string> v = {"This", "is", "an", "example"};
    
    std::string* p;
    std::size_t sz;
    std::tie(p, sz) = std::get_temporary_buffer<std::string>(v.size());
    sz = std::min(sz, v.size());
    
    std::uninitialized_copy_n(v.begin(), sz, p);
    
    for (std::string* i = p; i != p + sz; ++i)
    {
        std::cout << *i << ' ';
        i->~basic_string<char>();
    }
    std::cout << '\n';
    
    std::return_temporary_buffer(p);
}
|p=true
|output=
This is an example
}}

===Defect reports===
{{dr list begin}}
{{dr list item|wg=lwg|dr=2133|std=C++98|before=the effect description used a {{c/core|for}} loop with the iteration<br>expression {{c|++d_first, ++first, --n}}, which results<br>in argument-dependent lookups of {{c/core|operator,}}|after=discards the value<br>of one operand to<br>disable those ADLs}}
{{dr list item|wg=lwg|dr=2433|std=C++11|before=this algorithm might be hijacked by overloaded {{c/core|operator&}}|after=uses {{lc|std::addressof}}}}
{{dr list item|wg=lwg|dr=3870|std=C++20|before=this algorithm might create objects on a {{c/core|const}} storage|after=kept disallowed}}
{{dr list end}}

===See also===
{{dsc begin}}
{{dsc inc|cpp/memory/dsc uninitialized_copy}}
{{dsc inc|cpp/memory/ranges/dsc uninitialized_copy_n}}
{{dsc end}}

{{langlinks|de|es|fr|it|ja|pt|ru|zh}}