public member function
<string>

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

1
2
3
4
5
6
7
8
9
10
11
12
13
// 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:
buffer contains: string


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.

See also