Difference between revisions of "cpp/string/basic string/substr"
From cppreference.com
< cpp | string | basic string
(Added LWG issue #847 DR (part 13).) |
m (constexpr since-ification) |
||
(2 intermediate revisions by one user not shown) | |||
Line 2: | Line 2: | ||
{{cpp/string/basic_string/navbar}} | {{cpp/string/basic_string/navbar}} | ||
{{dcl begin}} | {{dcl begin}} | ||
− | {{dcl rev multi|num=1|until1=c++20|dcl1= | + | {{dcl rev multi|num=1|until1=c++23|notes1={{mark constexpr since c++20}}|dcl1= |
basic_string substr( size_type pos = 0, size_type count = npos ) const; | basic_string substr( size_type pos = 0, size_type count = npos ) const; | ||
− | + | |dcl2= | |
− | + | ||
− | + | ||
− | + | ||
constexpr basic_string | constexpr basic_string | ||
substr( size_type pos = 0, size_type count = npos ) const&; | substr( size_type pos = 0, size_type count = npos ) const&; | ||
Line 34: | Line 31: | ||
{{lc|std::out_of_range}} if {{c|pos > size()}}. | {{lc|std::out_of_range}} if {{c|pos > size()}}. | ||
− | {{cpp/strong exception safety guarantee}} | + | {{cpp/strong exception safety guarantee|plural=yes}} |
===Complexity=== | ===Complexity=== | ||
Line 74: | Line 71: | ||
std::cout << sub5 << '\n'; | std::cout << sub5 << '\n'; | ||
} | } | ||
− | catch (const std::out_of_range& | + | catch (const std::out_of_range& ex) |
{ | { | ||
− | std::cout << | + | std::cout << ex.what() << '\n'; |
} | } | ||
} | } | ||
+ | |p=true | ||
|output= | |output= | ||
abcdefghij | abcdefghij | ||
567 | 567 | ||
hij | hij | ||
− | + | basic_string::substr: __pos (which is 23) > this->size() (which is 20) | |
}} | }} | ||
Line 97: | Line 95: | ||
{{dsc inc|cpp/string/basic_string/dsc find}} | {{dsc inc|cpp/string/basic_string/dsc find}} | ||
{{dsc inc|cpp/string/basic_string/dsc npos}} | {{dsc inc|cpp/string/basic_string/dsc npos}} | ||
+ | {{dsc inc|cpp/string/basic_string_view/dsc {{SUBPAGENAMEE}}}} | ||
{{dsc end}} | {{dsc end}} | ||
{{langlinks|de|es|fr|it|ja|pt|ru|zh}} | {{langlinks|de|es|fr|it|ja|pt|ru|zh}} |
Latest revision as of 04:43, 12 April 2024
(1) | ||
basic_string substr( size_type pos = 0, size_type count = npos ) const; |
(until C++23) (constexpr since C++20) |
|
constexpr basic_string substr( size_type pos = 0, size_type count = npos ) const&; |
(since C++23) | |
constexpr basic_string substr( size_type pos = 0, size_type count = npos ) &&; |
(2) | (since C++23) |
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 |
[edit] Parameters
pos | - | position of the first character to include |
count | - | length of the substring |
[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
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)
[edit] 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 guarantee | added strong exception safety guarantee |
[edit] See also
copies characters (public member function) | |
returns the number of characters (public member function) | |
finds the first occurrence of the given substring (public member function) | |
constexpr size_type npos [static]
|
the special value size_type(-1), its exact meaning depends on the context |
returns a substring (public member function of std::basic_string_view<CharT,Traits> )
|