std::copy_n

template <class InputIterator, class Size, class OutputIterator>  OutputIterator copy_n (InputIterator first, Size n, OutputIterator result);

Copy elements

Copies the first n elements from the range beginning at first into the range beginning at result.

The function returns an iterator to the end of the destination range (which points to one past the last element copied).

If n is negative, the function does nothing.

If the ranges overlap, some of the elements in the range pointed by result may have undefined but valid values.

The behavior of this function template is equivalent to:

template<class InputIterator, class Size, class OutputIterator>
  OutputIterator copy_n (InputIterator first, Size n, OutputIterator result)
{
  while (n>0) {
    *result = *first;
    ++result; ++first;
    --n;
  }
  return result;
}

Parameters

first: Input iterators to the initial position in a sequence of at least n elements to be copied.
InputIterator shall point to a type assignable to the elements pointed by OutputIterator.
n: Number of elements to copy.
If this value is negative, the function does nothing.
Size shall be (convertible to) an integral type.
result: Output iterator to the initial position in the destination sequence of at least n elements.
This shall not point to any element in the range [first,last).

Return value

An iterator to the end of the destination range where elements have been copied.

Example

// copy_n algorithm example
#include <iostream>     // std::cout
#include <algorithm>    // std::copy
#include <vector>       // std::vector

int main () {
  int myints[]={10,20,30,40,50,60,70};
  std::vector<int> myvector;

  myvector.resize(7);   // allocate space for 7 elements

  std::copy_n ( myints, 7, myvector.begin() );

  std::cout << "myvector contains:";
  for (std::vector<int>::iterator it = myvector.begin(); it!=myvector.end(); ++it)
    std::cout << ' ' << *it;

  std::cout << '\n';

  return 0;
}

Output:

myvector contains: 10 20 30 40 50 60 70

Complexity

Linear in the distance between first and last: Performs an assignment operation for each element in the range.

Data races

The objects in the range of n elements pointed by first are accessed (each object is accessed exactly once).
The objects in the range between result and the returned value are modified (each object is modified exactly once).

Exceptions

Throws if either an element assignment or an operation on iterators throws.
Note that invalid arguments cause undefined behavior.