std::basic_string::substr(3)

NAME
std::basic_string::substr - std::basic_string::substr

Synopsis
   basic_string substr( size_type pos = 0, size_type count = npos ) (until C++20)
   const;
   constexpr basic_string substr( size_type pos = 0, size_type count = (since C++20)
   npos ) const;
   Returns a substring [pos, pos+count). If the requested substring extends past the
   end of the string, i.e. the count is greater than size() - pos (e.g. if count ==
   npos), the returned substring is [pos, size()).

Parameters
   pos - position of the first character to include
   count - length of the substring

Return value
   String containing the substring [pos, pos+count) or [pos, size()).

Exceptions
   std::out_of_range if pos > size()

Complexity
   Linear in count

Notes
   The returned string is constructed as if by basic_string(data()+pos, count), which
   implies that the returned string's allocator will be default-constructed — the new
   allocator might not be a copy of this->get_allocator().

Example
// Run this code
 #include <string>
 #include <iostream>
 int main()
 {
     std::string a = "0123456789abcdefghij";
     // count is npos, returns [pos, size())
     std::string sub1 = a.substr(10);
     std::cout << sub1 << '\n';
     // both pos and pos+count are within bounds, returns [pos, pos+count)
     std::string sub2 = a.substr(5, 3);
     std::cout << sub2 << '\n';
     // pos is within bounds, pos+count is not, returns [pos, size())
     std::string sub4 = a.substr(a.size()-3, 50);
     // this is effectively equivalent to
     // std::string sub4 = a.substr(17, 3);
     // since a.size() == 20, pos == a.size()-3 == 17, and a.size()-pos == 3
     std::cout << sub4 << '\n';
     try {
         // pos is out of bounds, throws
         std::string sub5 = a.substr(a.size()+3, 50);
         std::cout << sub5 << '\n';
     } catch(const std::out_of_range& e) {
         std::cout << "pos exceeds string size\n";
     }
 }

Output:
 abcdefghij
 567
 hij
 pos exceeds string size

See also
   copy copies characters
            (public member function)
   size returns the number of characters
   length (public member function)
   find find characters in the string
            (public member function)
   npos special value. The exact meaning depends on the context
   [static] (public static member constant)