Skip to main content

std::string find() method

// (1) Const version only
constexpr size_type find( const basic_string& str, size_type pos = 0 ) const noexcept;

// (2) Const version only
constexpr size_type find( const CharT* s, size_type pos, size_type count ) const;

// (3) Const version only
constexpr size_type find( const CharT* s, size_type pos = 0 ) const;

// (4) Const version only
constexpr size_type find( CharT ch, size_type pos = 0 ) const noexcept;

// (5) Const version only
template < class StringViewLike >
constexpr size_type find( const StringViewLike& t, size_type pos = 0 ) const noexcept(/* see below */);

Finds the first substring equal to the given character sequence.
Search begins at pos, i.e. the found substring must not begin in a position preceding pos.

  • (1) Finds the first substring equal to str.

  • (2) Finds the first substring equal to the range [ s, s + count ).
    This range may contain null characters.

  • (3) Finds the first substring equal to the character string pointed to by s.
    The length of the string is determined by the first null character using Traits::length(s).

  • (4) Finds the first character ch (treated as a single-character substring by the formal rules below).

  • (5) Implicitly converts t to a string view sv as if by std::basic_string_view<CharT, Traits> sv = t;, then finds the first substring equal to sv.

    Overload Resolution

    This overload participates in overload resolution only if std::is_convertible_v<const StringViewLike&, std::basic_string_view<CharT, Traits>> is true and std::is_convertible_v<const StringViewLike&, const CharT*> is false.

Formally, a substring str is said to be found at position xpos if all of the following are true:

  • xpos >= pos
  • xpos + str.size() <= size()
  • for all positions n in str, Traits::eq(at(xpos + n), str.at(n))

In particular, this implies that

  • a substring can be found only if pos <= size() - str.size()
  • an empty substring is found at pos if and only if pos <= size()
  • for a non-empty substring, if pos >= size(), the function always returns npos.

Parameters​

  • str - string to search for
  • pos - position at which to start the search
  • count - length of substring to search for
  • s - pointer to a character string to search for
  • ch - character to search for
  • t - object (convertible to std::basic_string_view) to search for

Return value​

Position of the first character of the found substring or npos if no such substring is found.

Complexity​

important

This section requires improvement. You can help by editing this doc page.

Exceptions​

  • (1-4) (none)
  • (5) noexcept specification: 
    noexcept(std::is_nothrow_convertible_v<const T&, std::basic_string_view<CharT, Traits>>)

Example​

#include <string>
#include <iostream>
 
void print(std::string::size_type n, std::string const &s)
{
    if (n == std::string::npos) {
        std::cout << "not found\n";
    } else {
        std::cout << "found: " << s.substr(n) << '\n';
    }
}
 
int main()
{
    std::string::size_type n;
    std::string const s = "This is a string";
 
    // search from beginning of string
    n = s.find("is");
    print(n, s);
 
    // search from position 5
    n = s.find("is", 5);
    print(n, s);
 
    // find a single character
    n = s.find('a');
    print(n, s);
 
    // find a single character
    n = s.find('q');
    print(n, s);
}
Output
found: is is a string
found: is a string
found: a string
not found
This article originates from this CppReference page. It was likely altered for improvements or editors' preference. Click "Edit this page" to see all changes made to this document.
Hover to see the original license.

std::string find() method

// (1) Const version only
constexpr size_type find( const basic_string& str, size_type pos = 0 ) const noexcept;

// (2) Const version only
constexpr size_type find( const CharT* s, size_type pos, size_type count ) const;

// (3) Const version only
constexpr size_type find( const CharT* s, size_type pos = 0 ) const;

// (4) Const version only
constexpr size_type find( CharT ch, size_type pos = 0 ) const noexcept;

// (5) Const version only
template < class StringViewLike >
constexpr size_type find( const StringViewLike& t, size_type pos = 0 ) const noexcept(/* see below */);

Finds the first substring equal to the given character sequence.
Search begins at pos, i.e. the found substring must not begin in a position preceding pos.

  • (1) Finds the first substring equal to str.

  • (2) Finds the first substring equal to the range [ s, s + count ).
    This range may contain null characters.

  • (3) Finds the first substring equal to the character string pointed to by s.
    The length of the string is determined by the first null character using Traits::length(s).

  • (4) Finds the first character ch (treated as a single-character substring by the formal rules below).

  • (5) Implicitly converts t to a string view sv as if by std::basic_string_view<CharT, Traits> sv = t;, then finds the first substring equal to sv.

    Overload Resolution

    This overload participates in overload resolution only if std::is_convertible_v<const StringViewLike&, std::basic_string_view<CharT, Traits>> is true and std::is_convertible_v<const StringViewLike&, const CharT*> is false.

Formally, a substring str is said to be found at position xpos if all of the following are true:

  • xpos >= pos
  • xpos + str.size() <= size()
  • for all positions n in str, Traits::eq(at(xpos + n), str.at(n))

In particular, this implies that

  • a substring can be found only if pos <= size() - str.size()
  • an empty substring is found at pos if and only if pos <= size()
  • for a non-empty substring, if pos >= size(), the function always returns npos.

Parameters​

  • str - string to search for
  • pos - position at which to start the search
  • count - length of substring to search for
  • s - pointer to a character string to search for
  • ch - character to search for
  • t - object (convertible to std::basic_string_view) to search for

Return value​

Position of the first character of the found substring or npos if no such substring is found.

Complexity​

important

This section requires improvement. You can help by editing this doc page.

Exceptions​

  • (1-4) (none)
  • (5) noexcept specification: 
    noexcept(std::is_nothrow_convertible_v<const T&, std::basic_string_view<CharT, Traits>>)

Example​

#include <string>
#include <iostream>
 
void print(std::string::size_type n, std::string const &s)
{
    if (n == std::string::npos) {
        std::cout << "not found\n";
    } else {
        std::cout << "found: " << s.substr(n) << '\n';
    }
}
 
int main()
{
    std::string::size_type n;
    std::string const s = "This is a string";
 
    // search from beginning of string
    n = s.find("is");
    print(n, s);
 
    // search from position 5
    n = s.find("is", 5);
    print(n, s);
 
    // find a single character
    n = s.find('a');
    print(n, s);
 
    // find a single character
    n = s.find('q');
    print(n, s);
}
Output
found: is is a string
found: is a string
found: a string
not found
This article originates from this CppReference page. It was likely altered for improvements or editors' preference. Click "Edit this page" to see all changes made to this document.
Hover to see the original license.