public member function

std::basic_string::copy

size_type copy (charT* s, size_type len, size_type pos = 0) const;

Copy sequence of characters from string

Copies a substring of the current value of the basic_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 basic_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).

Member type

size_type is an unsigned integral 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 basic_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.