NAME¶

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

Synopsis¶

basic_string substr( size_type pos = 0, size_type (until C++23)
count = npos ) const; (constexpr since C++20)
constexpr basic_string
substr( size_type pos = 0, size_type count = (1) (since C++23)
npos ) const&;
constexpr basic_string substr( size_type pos = 0, (2) (since C++23)
size_type count = npos ) &&;

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()).

1) Equivalent to return basic_string(*this, pos, count);.
2) Equivalent to return basic_string(std::move(*this), pos, count);.

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().

If an exception is thrown for any reason, these functions have no effect (strong
exception safety guarantee).

Complexity¶

Linear in count.

Notes¶

The allocator of the returned string is default-constructed: the new allocator might
not be a copy of get_allocator().

Example¶

// Run this code

#include <iostream>
#include <string>

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& ex)
{
std::cout << ex.what() << '\n';
}
}

Possible output:¶

abcdefghij
567
hij
basic_string::substr: __pos (which is 23) > this->size() (which is 20)

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¶

copy copies characters
(public member function)
size returns the number of characters
length (public member function)
find finds the first occurrence of the given substring
(public member function)
npos special value. The exact meaning depends on the context
[static] (public static member constant)
substr returns a substring
(public member function of std::basic_string_view<CharT,Traits>)