std::basic_string<CharT,Traits,Allocator>::substr

From cppreference.com
< cpp‎ | string‎ | basic string
 
 
 
std::basic_string
Member functions
Element access
Iterators
Capacity
Operations
basic_string::substr
Search
Constants
Deduction guides (C++17)
Non-member functions
I/O
Comparison
(until C++20)(until C++20)(until C++20)(until C++20)(until C++20)(C++20)
Numeric conversion
(C++11)(C++11)(C++11)
(C++11)(C++11)
(C++11)(C++11)(C++11)
(C++11)
(C++11)
Helper classes
 
basic_string substr( size_type pos = 0, size_type count = npos ) const;
(until C++20)
constexpr basic_string substr( size_type pos = 0, size_type count = npos ) const;
(since C++20)

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

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

Complexity

Linear in count

Notes

The returned string is constructed as if by basic_string(data()+pos, count), which implies that the returned string's allocator will be default-constructed — the new allocator might not be a copy of this->get_allocator().

Example

#include <string>
#include <iostream>
 
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& e) {
        std::cout << "pos exceeds string size\n";
    }
}

Output:

abcdefghij
567
hij
pos exceeds string size

See also

copies characters
(public member function)
returns the number of characters
(public member function)
find characters in the string
(public member function)
[static]
special value. The exact meaning depends on the context
(public static member constant)