Namespaces
Variants
Views
Actions

Difference between revisions of "cpp/string/basic string/substr"

From cppreference.com
< cpp‎ | string‎ | basic string
(P0980R1, remove std::string:: since it requires a specified specialization (std::basic_string::npos might be better but it's invalid))
m (constexpr since-ification)
 
(11 intermediate revisions by 6 users not shown)
Line 1: Line 1:
−
{{cpp/string/basic_string/title | substr}}
+
{{cpp/string/basic_string/title|substr}}
 
{{cpp/string/basic_string/navbar}}
 
{{cpp/string/basic_string/navbar}}
 
{{dcl begin}}
 
{{dcl begin}}
−
{{dcl rev multi | 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=
+
|dcl2=
−
constexpr basic_string substr( size_type pos = 0, size_type count = npos ) const;
+
constexpr basic_string
 +
    substr( size_type pos = 0, size_type count = npos ) const&;
 +
}}
 +
{{dcl|num=2|since=c++23|1=
 +
constexpr basic_string substr( size_type pos = 0, size_type count = npos ) &&;
 
}}
 
}}
 
{{dcl end}}
 
{{dcl end}}
  
−
Returns a substring {{tt|[pos, pos+count)}}. If the requested substring extends past the end of the string, or if {{c|1=count == npos}}, the returned substring is {{tt|[pos, }}[[cpp/string/basic_string/size|{{tt|size()}}]]{{tt|)}}.  
+
Returns a substring {{range|pos|pos + count}}. If the requested substring extends past the end of the string, i.e. the {{c|count}} is greater than {{c|size() - pos}} (e.g. if {{c|1=count == npos}}), the returned substring is {{range/core|{{c|pos}}|{{rlpf|size}}}}.
 +
 
 +
@1@ Equivalent to {{c|return basic_string(*this, pos, count);}}.
 +
 
 +
@2@ Equivalent to {{c|return basic_string(std::move(*this), pos, count);}}.
  
 
===Parameters===
 
===Parameters===
 
{{par begin}}
 
{{par begin}}
−
{{par | pos | position of the first character to include}}
+
{{par|pos|position of the first character to include}}
−
{{par | count | length of the substring}}
+
{{par|count|length of the substring}}
−
{{par end}}  
+
{{par end}}
  
 
===Return value===
 
===Return value===
−
String containing the substring {{tt|[pos, pos+count)}}.
+
String containing the substring {{range|pos|pos + count}} or {{range/core|{{c|pos}}|{{rlpf|size}}}}.
  
 
===Exceptions===
 
===Exceptions===
−
{{lc|std::out_of_range}} if {{tt|pos > }}[[cpp/string/basic_string/size|{{tt|size()}}]]
+
{{lc|std::out_of_range}} if {{c|pos > size()}}.
 +
 
 +
{{cpp/strong exception safety guarantee|plural=yes}}
  
 
===Complexity===
 
===Complexity===
−
Linear in {{tt|count}}
+
Linear in {{c|count}}.
  
 
===Notes===
 
===Notes===
−
 
+
The allocator of the returned string is default-constructed: the new allocator might ''not'' be a copy of {{rlpf|get_allocator}}.
−
The returned string is constructed as if by {{c|basic_string(data()+pos, count)}}, which implies that the returned string's allocator will be default-constructed — the new allocator will ''not'' be a copy of {{tt|this->}}[[cpp/string/basic_string/get_allocator|{{tt|get_allocator()}}]].
+
  
 
===Example===
 
===Example===
 
{{example
 
{{example
−
| code=
+
|code=
−
#include <string>
+
 
#include <iostream>
 
#include <iostream>
 +
#include <string>
 
   
 
   
 
int main()
 
int main()
Line 43: Line 52:
 
     std::string sub1 = a.substr(10);
 
     std::string sub1 = a.substr(10);
 
     std::cout << sub1 << '\n';
 
     std::cout << sub1 << '\n';
−
+
   
−
     // both pos and pos+count are within bounds, returns [pos, pos+count)
+
     // both pos and pos + count are within bounds, returns [pos, pos + count)
 
     std::string sub2 = a.substr(5, 3);
 
     std::string sub2 = a.substr(5, 3);
 
     std::cout << sub2 << '\n';
 
     std::cout << sub2 << '\n';
−
 
+
   
−
     // pos is within bounds, pos+count is not, returns [pos, size())  
+
     // pos is within bounds, pos + count is not, returns [pos, size())
−
     std::string sub4 = a.substr(a.size()-3, 50);
+
     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';
 
     std::cout << sub4 << '\n';
  
−
     try {
+
     try
 +
    {
 
         // pos is out of bounds, throws
 
         // pos is out of bounds, throws
−
         std::string sub5 = a.substr(a.size()+3, 50);
+
         std::string sub5 = a.substr(a.size() + 3, 50);
 
         std::cout << sub5 << '\n';
 
         std::cout << sub5 << '\n';
−
     } catch(const std::out_of_range& e) {
+
     }
−
         std::cout << "pos exceeds string size\n";
+
    catch (const std::out_of_range& ex)
 +
    {
 +
         std::cout << ex.what() << '\n';
 
     }
 
     }
 
}
 
}
−
| output=
+
|p=true
 +
|output=
 
abcdefghij
 
abcdefghij
 
567
 
567
 
hij
 
hij
−
pos exceeds string size
+
basic_string::substr: __pos (which is 23) > this->size() (which is 20)
 
}}
 
}}
 +
 +
===Defect reports===
 +
{{dr list begin}}
 +
{{dr list item|wg=lwg|dr=847|std=C++98|before=there was no exception safety guarantee|after=added strong exception safety guarantee}}
 +
{{dr list end}}
  
 
===See also===
 
===See also===
 
{{dsc begin}}
 
{{dsc begin}}
−
{{dsc inc | cpp/string/basic_string/dsc copy}}
+
{{dsc inc|cpp/string/basic_string/dsc copy}}
−
{{dsc inc | cpp/string/basic_string/dsc size}}
+
{{dsc inc|cpp/string/basic_string/dsc size}}
−
{{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

 
C++
 
Strings library
 
std::basic_string
Member functions
(C++23)
Element access
(DR*)
(DR*)
(C++17)
Iterators
(C++11)
(C++11)
(C++11)
(C++11)
Capacity
(DR*)
Modifiers
(C++23)
(DR*)
(C++23)
(C++23)
(C++23)  
Search
Operations
(C++20)
(C++20)
(C++23)
basic_string::substr
Constants
Non-member functions
(C++20)(C++20)
I/O
Comparison
(until C++20)(until C++20)(until C++20)(until C++20)(until C++20)(C++20)
Numeric conversions
(C++11)(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)(C++11)
(C++11)
(C++11)
Literals
(C++14)
Helper classes
(C++11)
Deduction guides (C++17)

 
(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) [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]
Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/string/basic_string/substr&oldid=170797"