std::basic_string<CharT,Traits,Allocator>::substr - cppreference.com (original) (raw)

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

Contents

• 1 Parameters
• 2 Return value
• 3 Exceptions
• 4 Complexity
• 5 Notes
• 6 Example
• 7 Defect reports
• 8 See also

[edit] Parameters

[edit] Return value

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

[edit] 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).

[edit] Complexity

Linear in count.

[edit] Notes

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

[edit] Example

#include #include   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)

[edit] Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

[edit] See also

| | copies characters (public member function) [edit] | | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | returns the number of characters (public member function) [edit] | | | | finds the first occurrence of the given substring (public member function) [edit] | | | constexpr size_type npos [static] | the special value size_type(-1), its exact meaning depends on the context[edit] | | | returns a substring (public member function of std::basic_string_view<CharT,Traits>) [edit] | |