From cppreference.com
Defined in header
Call signature
template<std::input_iteratorI,std::weakly_incrementableO>requiresstd::indirectly_copyable<I,O>constexprranges::copy_n_result<I,O>copy_n(Ifirst,std::iter_difference_t<I>count,Od_first); (1) (since C++20)template</*execution-policy*/Ep,std::random_access_iteratorI,std::random_access_iteratorO,std::sized_sentinel_for<O>OutS>requiresstd::indirectly_copyable<I,O>ranges::copy_n_result<I,O>copy_n(Ep&&policy,Ifirst,iter_difference_t<I>count,Od_first,OutSd_last); (2) (since C++26)Helper type
template<classI,classO>usingcopy_n_result=ranges::in_out_result<I,O>; (3) (since C++20)For the definition of /*execution-policy*/, see
.
If count is positive, copies the elements in the source range [first, ranges::next(first,count)) to the destination range. Otherwise do nothing.
1) The destination range is [d_first, ranges::next(d_first,count)).
2) The copy order is determined by policy, and the destination range is [d_first, d_last). If the destination range is exhausted before reaching the end of the source range, the remaining elements in the source range will not be copied.
The function-like entities described on this page are
(informally known as niebloids), that is:
Explicit template argument lists cannot be specified when calling any of them.
None of them are visible to
.
When any of them are found by
as the name to the left of the function-call operator,
is inhibited.
Parameters
first - the beginning of the source range count - number of the elements to copy d_first - the beginning of the destination range policy - the
to use Return value
A ranges::copy_n_result object where:
The data member
holds an iterator past the last copied element in the source range, or an iterator to the beginning of the source range if no element is copied.
The data member
holds an iterator past the last copy-assigned element in the destination range, or d_first if no element is copied.
Complexity
Given
N1 as max(count,0), and
N2 as ranges::distance(d_first,d_last):
1) Exactly N1 assignments.
2) Exactly min(N1,N2) assignments.
Exceptions
2) During the execution process:
If the temporary memory resources required for parallelization are not available,
is thrown.
If an uncaught exception is thrown while accessing objects via an algorithm argument, the behavior is determined by the execution policy (for
,
is invoked).
Notes
In practice, implementations of ranges::copy_n may avoid multiple assignments and use bulk copy functions such as
if the value type is
and the iterator types satisfy
. Alternatively, such copy acceleration can be injected during an optimization phase of a compiler.
When copying overlapping ranges, ranges::copy_n is appropriate when copying to the left (beginning of the destination range is outside the source range) while
is appropriate when copying to the right (end of the destination range is outside the source range).
Possible implementation
structcopy_n_fn{template<std::input_iteratorI,std::weakly_incrementableO>requiresstd::indirectly_copyable<I,O>constexprranges::copy_n_result<I,O>operator()(Ifirst,std::iter_difference_t<I>n,Od_first)const{for(;n-->0;(void)++first,(void)++d_first)*d_first=*first;return{std::move(first),std::move(d_first)};}};inlineconstexprcopy_n_fncopy_n{};Example
Run this code
#include<algorithm>#include<iomanip>#include<iostream>#include<iterator>#include<string>#include<string_view>intmain(){conststd::string_viewin{"ABCDEFGH"};std::stringout;std::ranges::copy_n(in.begin(),4,std::back_inserter(out));std::cout<<std::quoted(out)<<'\n';out="abcdefgh";constautores{std::ranges::copy_n(in.begin(),5,out.begin())};constautoi{std::distance(std::begin(in),res.in)};constautoj{std::distance(std::begin(out),res.out)};std::cout<<"in["<<i<<"] = '"<<in[i]<<"'\n"<<"out["<<j<<"] = '"<<out[j]<<"'\n";}Output:
"ABCD" in[5] = 'F' out[5] = 'f' See also
(C++11)
copies a number of elements to a new location
(function template)
(C++20)(C++20)
copies a range of elements to a new location
(algorithm function object)
(C++20)
copies a range of elements in backwards order
(algorithm function object)
ranges::remove_copyranges::remove_copy_if
(C++20)(C++20)
copies a range of elements omitting those that satisfy specific criteria
(algorithm function object)
ranges::replace_copyranges::replace_copy_if
(C++20)(C++20)
copies a range, replacing elements satisfying specific criteria with another value
(algorithm function object)
(C++20)
creates a copy of a range that is reversed
(algorithm function object)
(C++20)
copies and rotate a range of elements
(algorithm function object)
(C++20)
creates a copy of some range of elements that contains no consecutive duplicates
(algorithm function object)
(C++20)
moves a range of elements to a new location
(algorithm function object)
(C++20)
moves a range of elements to a new location in backwards order
(algorithm function object)