Namespaces
Variants
Views
Actions

std::ranges::copy_n, std::ranges::copy_n_result

From cppreference.com
< cpp‎ | algorithm‎ | ranges
 
 
Algorithm library
Constrained algorithms and algorithms on ranges (C++20)
Constrained algorithms, e.g. ranges::copy, ranges::sort, ...
Execution policies (C++17)
Non-modifying sequence operations
Batch operations
(C++17)
Search operations
(C++11)                (C++11)(C++11)

Modifying sequence operations
Copy operations
(C++11)
(C++11)
Swap operations
Transformation operations
Generation operations
Removing operations
Order-changing operations
(until C++17)(C++11)
(C++20)(C++20)
Sampling operations
(C++17)

Sorting and related operations
Partitioning operations
Sorting operations
Binary search operations
(on partitioned ranges)
Set operations (on sorted ranges)
Merge operations (on sorted ranges)
Heap operations
Minimum/maximum operations
(C++11)
(C++17)
Lexicographical comparison operations
Permutation operations
C library
Numeric operations
Operations on uninitialized memory
 
Constrained algorithms
All names in this menu belong to namespace std::ranges
Non-modifying sequence operations
Modifying sequence operations
Partitioning operations
Sorting operations
Binary search operations (on sorted ranges)
       
       
Set operations (on sorted ranges)
Heap operations
Minimum/maximum operations
       
       
Permutation operations
Fold operations
Numeric operations
(C++23)            
Operations on uninitialized storage
Return types
 
Defined in header <algorithm>
Call signature
template< std::input_iterator I, std::weakly_incrementable O >

requires std::indirectly_copyable<I, O>
constexpr copy_n_result<I, O>

    copy_n( I first, std::iter_difference_t<I> n, O result );
(1) (since C++20)
Helper type
template< class I, class O >
using copy_n_result = ranges::in_out_result<I, O>;
(2) (since C++20)
1) Copies exactly n values from the range beginning at first to the range beginning at result by performing *(result + i) = *(first + i) for each integer in [0n). The behavior is undefined if result is within the range [firstfirst + n) (ranges::copy_backward might be used instead in this case).

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

Contents

[edit] Parameters

first - the beginning of the range of elements to copy from
n - number of the elements to copy
result - the beginning of the destination range

[edit] Return value

ranges::copy_n_result{first + n, result + n} or more formally, a value of type ranges::in_out_result that contains an input_iterator iterator equals to ranges::next(first, n) and a weakly_incrementable iterator equals to ranges::next(result, n).

[edit] Complexity

Exactly n assignments.

[edit] Notes

In practice, implementations of std::ranges::copy_n may avoid multiple assignments and use bulk copy functions such as std::memmove if the value type is TriviallyCopyable and the iterator types satisfy contiguous_iterator. Alternatively, such copy acceleration can be injected during an optimization phase of a compiler.

When copying overlapping ranges, std::ranges::copy_n is appropriate when copying to the left (beginning of the destination range is outside the source range) while std::ranges::copy_backward is appropriate when copying to the right (end of the destination range is outside the source range).

[edit] Possible implementation

struct copy_n_fn
{
    template<std::input_iterator I, std::weakly_incrementable O>
    requires std::indirectly_copyable<I, O>
    constexpr ranges::copy_n_result<I, O>
        operator()(I first, std::iter_difference_t<I> n, O result) const
    {
        for (; n-- > 0; (void)++first, (void)++result)
            *result = *first;
 
        return {std::move(first), std::move(result)};
    }
};
 
inline constexpr copy_n_fn copy_n{};

[edit] Example

#include <algorithm>
#include <iomanip>
#include <iostream>
#include <iterator>
#include <string>
#include <string_view>
 
int main()
{
    const std::string_view in{"ABCDEFGH"};
    std::string out;
 
    std::ranges::copy_n(in.begin(), 4, std::back_inserter(out));
    std::cout << std::quoted(out) << '\n';
 
    out = "abcdefgh";
    const auto res{std::ranges::copy_n(in.begin(), 5, out.begin())};
    const auto i{std::distance(std::begin(in), res.in)};
    const auto j{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'

[edit] See also

copies a range of elements to a new location
(algorithm function object)[edit]
copies a range of elements in backwards order
(algorithm function object)[edit]
copies a range of elements omitting those that satisfy specific criteria
(algorithm function object)[edit]
copies a range, replacing elements satisfying specific criteria with another value
(algorithm function object)[edit]
creates a copy of a range that is reversed
(algorithm function object)[edit]
copies and rotate a range of elements
(algorithm function object)[edit]
creates a copy of some range of elements that contains no consecutive duplicates
(algorithm function object)[edit]
moves a range of elements to a new location
(algorithm function object)[edit]
moves a range of elements to a new location in backwards order
(algorithm function object)[edit]
(C++11)
copies a number of elements to a new location
(function template) [edit]