public member function

std::basic_string::substr

basic_string substr (size_type pos = 0, size_type len = npos) const;

Generate substring

Returns a newly constructed basic_string object with its value initialized to a copy of a substring of this object.

The substring is the portion of the object that starts at character position pos and spans len characters (or until the end of the string, whichever comes first).

Parameters

pos: Position of the first character to be copied as a substring.
If this is equal to the string length, the function returns an empty string.
If this is greater than the string length, it throws out_of_range.
Note: The first character is denoted by a value of 0 (not 1).
len: Number of characters to include in the substring (if the string is shorter, as many characters as possible are used).
A value of basic_string::npos indicates all characters until the end of the string.

Member type size_type is an unsigned integral type.

Return Value

A basic_string object with a substring of this object.

Example

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

int main ()
{
  std::string str="We think in generalities, but we live in details.";
                                              // (quoting Alfred N. Whitehead)

  std::string str2 = str.substr (12,12);         // "generalities"

  std::string::size_type pos = str.find("live"); // position of "live" in str

  std::string str3 = str.substr (pos);           // get from "live" to the end

  std::cout << str2 << ' ' << str3 << '\n';

  return 0;
}

Output:

generalities live in details.

Complexity

Unspecified, but generally linear in the length of the returned object.

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 pos is greater than the string length, an out_of_range exception is thrown.
If the type uses the default allocator, a bad_alloc exception is thrown if the function needs to allocate storage and fails.