std::copy_n (3) - Linux Man Pages

std::copy_n: std::copy_n

NAME

std::copy_n - std::copy_n

Synopsis


Defined in header <algorithm>
template< class InputIt, class Size, class OutputIt > (since C++11)
OutputIt copy_n( InputIt first, Size count, OutputIt result ); (until C++20)
template< class InputIt, class Size, class OutputIt > (1) (since C++20)
constexpr OutputIt copy_n( InputIt first, Size count, OutputIt result );
template< class ExecutionPolicy, class ForwardIt1, class Size, class ForwardIt2 > (2) (since C++17)
ForwardIt2 copy_n( ExecutionPolicy&& policy, ForwardIt1 first, Size count, ForwardIt2 result );


1) Copies exactly count values from the range beginning at first to the range beginning at result. Formally, for each non-negative integer i < n, performs *(result + i) = *(first + i). Overlap of ranges is not permitted.
2) Same as (1), but executed according to policy. This overload only participates in overload resolution if std::is_execution_policy_v<std::decay_t<ExecutionPolicy>> is true

Parameters


first - the beginning of the range of elements to copy from
count - number of the elements to copy
result - the beginning of the destination range
policy - the execution policy to use. See execution_policy for details.

Type requirements


-
InputIt must meet the requirements of LegacyInputIterator.
-
OutputIt must meet the requirements of LegacyOutputIterator.
-
ForwardIt1, ForwardIt2 must meet the requirements of LegacyForwardIterator.

Return value


Iterator in the destination range, pointing past the last element copied if count>0 or result otherwise.

Complexity


Exactly count assignments, if count>0.

Exceptions


The overload with a template parameter named ExecutionPolicy reports errors as follows:


* If execution of a function invoked as part of the algorithm throws an exception and ExecutionPolicy is one of the standard_policies, std::terminate is called. For any other ExecutionPolicy, the behavior is implementation-defined.
* If the algorithm fails to allocate memory, std::bad_alloc is thrown.

Possible implementation


  template< class InputIt, class Size, class OutputIt>
  OutputIt copy_n(InputIt first, Size count, OutputIt result)
  {
      if (count > 0) {
          *result++ = *first;
          for (Size i = 1; i < count; ++i) {
              *result++ = *++first;
          }
      }
      return result;
  }

Example


// Run this code


  #include <iostream>
  #include <string>
  #include <algorithm>
  #include <iterator>


  int main()
  {
      std::string in = "1234567890";
      std::string out;


      std::copy_n(in.begin(), 4, std::back_inserter(out));
      std::cout << out << '\n';
  }

Output:


  1234

See also


copy
copy_if copies a range of elements to a new location
        (function template)


(C++11)