std::copy

Defined in header <algorithm>

template< class InputIt, class OutputIt >
OutputIt copy( InputIt first, InputIt last, OutputIt d_first );

(1)

template< class InputIt, class OutputIt, class UnaryPredicate >
OutputIt copy_if( InputIt first, InputIt last,
                  OutputIt d_first,
                  UnaryPredicate pred );

(2)

(since C++11)

Copies the elements in the range, defined by [first, last), to another range beginning at d_first. The second function only copies the elements for which the predicate pred returns true. The order of the elements that are not removed is preserved.

For std::copy, the behavior is undefined if d_first is within the range [first, last). In this case, std::copy_backward may be used instead.

For std::copy_if, the behavior is undefined if the source and the destination ranges overlap.

Parameters

first, last	-	the range of elements to copy
d_first	-	the beginning of the destination range.
pred	-	unary predicate which returns `true` for the required elements. The signature of the predicate function should be equivalent to the following: `bool pred(const Type &a);` The signature does not need to have `const &`, but the function must not modify the objects passed to it. The type `Type` must be such that an object of type `InputIt` can be dereferenced and then implicitly converted to `Type`.
Type requirements
- `InputIt` must meet the requirements of `InputIterator`.
- `OutputIt` must meet the requirements of `OutputIterator`.
- `UnaryPredicate` must meet the requirements of `Predicate`.

Return value

Output iterator to the element in the destination range, one past the last element copied.

Complexity

1) Exactly last - first assignments.

2) Exactly last - first applications of the predicate.

Notes

In practice, implementations of std::copy avoid multiple assignments and use bulk copy functions such as std::memmove if the value type is TriviallyCopyable.

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

Possible implementation

First version

template<class InputIt, class OutputIt>
OutputIt copy(InputIt first, InputIt last, 
              OutputIt d_first)
{
    while (first != last) {
        *d_first++ = *first++;
    }
    return d_first;
}

Second version

template<class InputIt, class OutputIt, class UnaryPredicate>
OutputIt copy_if(InputIt first, InputIt last, 
                 OutputIt d_first, UnaryPredicate pred)
{
    while (first != last) {
        if (pred(*first))
            *d_first++ = *first;
        first++;
    }
    return d_first;
}

Example

The following code uses copy to both copy the contents of one vector to another and to display the resulting vector:

#include <algorithm>
#include <iostream>
#include <vector>
#include <iterator>
#include <numeric>
  
int main()
{
    std::vector<int> from_vector(10);
    std::iota(from_vector.begin(), from_vector.end(), 0);
  
    std::vector<int> to_vector;
    std::copy(from_vector.begin(), from_vector.end(),
              std::back_inserter(to_vector));
// or, alternatively,
//  std::vector<int> to_vector(from_vector.size());
//  std::copy(from_vector.begin(), from_vector.end(), to_vector.begin());
// either way is equivalent to
//  std::vector<int> to_vector = from_vector;
  
    std::cout << "to_vector contains: ";
  
    std::copy(to_vector.begin(), to_vector.end(),
              std::ostream_iterator<int>(std::cout, " "));
    std::cout << '\n';
}

Output:

1	`to_vector contains: 0 1 2 3 4 5 6 7 8 9`

copy_backward	copies a range of elements in backwards order (function template)
copy_n (C++11)	copies a number of elements to a new location (function template)
fill	assigns a range of elements a certain value (function template)
remove_copyremove_copy_if	copies a range of elements omitting those that satisfy specific criteria (function template)
std::experimental::parallel::copy (parallelism TS)	parallelized version of `std::copy` (function template)
std::experimental::parallel::copy_if (parallelism TS)	parallelized version of `std::copy_if` (function template)

Links:

http://en.cppreference.com/w/cpp/algorithm/copy

doc_CPP

2025-01-10 15:47:30

Comments