std::basic_string::copy(3)

NAME
std::basic_string::copy - std::basic_string::copy

Synopsis
   size_type copy( CharT* dest, size_type count, size_type pos (constexpr since C++20)
   = 0 ) const;
   Copies a substring [pos, pos + count) to character string pointed to by dest. If the
   requested substring lasts past the end of the string, or if count == npos, the
   copied substring is [pos, size()).
   The resulting character string is not null-terminated.

Parameters
   dest - pointer to the destination character string
   count - length of the substring
   pos - position of the first character to include

Return value
   Number of characters copied.

Exceptions
   std::out_of_range if pos > size().
   If an exception is thrown for any reason, this function has no effect (strong
   exception safety guarantee).

Complexity
   Linear in count.

Example
// Run this code
 #include <iostream>
 #include <string>
 int main()
 {
     std::string foo("WINE");
     // brace-initialization initializes all characters to 0,
     // providing a null-terminator
     char bar[4]{};
     // do not copy the last char, to guarantee null-termination
     foo.copy(bar, sizeof bar - 1);
     std::cout << bar << '\n'; // requires bar to be null-terminated
 }

Output:
 WIN
   Defect reports
   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.
     DR Applied to Behavior as published Correct behavior
   LWG 847 C++98 there was no exception safety added strong exception safety
                      guarantee guarantee

See also
   substr returns a substring
           (public member function)
   copy copies characters
           (public member function of std::basic_string_view<CharT,Traits>)
   copy copies a range of elements to a new location
   copy_if (function template)
   (C++11)
   memcpy copies one buffer to another
           (function)