# std::basic_string<CharT,Traits,Allocator>::find

From cppreference.com
< cpp‎ | string‎ | basic string

| (1) |
size_type find( const basic_string& str, size_type pos = 0 ) const; |  | (until C++11)
size_type find( const basic_string& str, size_type pos = 0 ) const noexcept; |  | (since C++11)
size_type find( const CharT* s, size_type pos, size_type count ) const; | (2) |
size_type find( const CharT* s, size_type pos = 0 ) const; | (3) |
| (4) |
size_type find( CharT ch, size_type pos = 0 ) const; |  | (until C++11)
size_type find( CharT ch, size_type pos = 0 ) const noexcept; |  | (since C++11)
template < class T > size_type find( const T& t, size_type pos = 0 ) const noexcept(/* see below */); | (5) | (since C++17)

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`. This overload only participates in overload resolution if std::is_convertible_v <const T&, std::basic_string_view <CharT, Traits>> is true and std::is_convertible_v <const T&, const CharT*> is false.

Formally, a substring `str` is said to be found at position `xpos` if all of the following is 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.

### Exceptions

2-3) Throws nothing.
5)
`noexcept` specification:
noexcept(std::is_nothrow_convertible_v<const T&, std::basic_string_view <CharT, Traits>>)

### 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 2946 | C++17 | `string_view` overload causes ambiguity in some cases | avoided by making it a template

### Example

Run this code

    #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

### See also

strstr | finds the first occurrence of a substring of characters (function)
wcsstr | finds the first occurrence of a wide string within another wide string (function)
strchr | finds the first occurrence of a character (function)
wcschr | finds the first occurrence of a wide character in a wide string (function)
rfind | find the last occurrence of a substring (public member function)
find_first_of | find first occurrence of characters (public member function)
find_first_not_of | find first absence of characters (public member function)
find_last_of | find last occurrence of characters (public member function)
find_last_not_of | find last absence of characters (public member function)
search | searches for a range of elements (function template)

Retrieved from "https://en.cppreference.com/mwiki/index.php?title=cpp/string/basic_string/find&oldid=107722"