public member function

std::string::copy

size_t copy (char* s, size_t len, size_t pos = 0) const;

Copy sequence of characters from string

Copies a substring of the current value of the string object into the array pointed by s. This substring contains the len characters that start at position pos.

The function does not append a null character at the end of the copied content.

Parameters

s: Pointer to an array of characters.
The array shall contain enough storage for the copied characters.
len: Number of characters to copy (if the string is shorter, as many characters as possible are copied).
pos: Position of the first character to be copied.
If this is greater than the string length, it throws out_of_range.
Note: The first character in the string is denoted by a value of 0 (not 1).

Return value

The number of characters copied to the array pointed by s. This may be equal to len or to length()-pos (if the string value is shorter than pos+len).

size_t is an unsigned integral type (the same as member type string::size_type).

Example

// string::copy
#include <iostream>
#include <string>

int main ()
{
  char buffer[20];
  std::string str ("Test string...");
  std::size_t length = str.copy(buffer,6,5);
  buffer[length]='\0';
  std::cout << "buffer contains: " << buffer << '\n';
  return 0;
}

Output:

Complexity

Linear in the number of characters copied.

Iterator validity

No changes.

Data races

The object is accessed.

Exception safety

Strong guarantee: if an exception is thrown, there are no changes in the string.

If s does not point to an array long enough, it causes undefined behavior.

If pos is greater than the string length, an out_of_range exception is thrown.