std::basic_string<CharT,Traits,Allocator>::find
(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
instr
,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 ifpos <= size()
- for a non-empty substring, if
pos >= size()
, the function always returnsnpos
.
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
#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
finds the first occurrence of a substring of characters (function) |
|
finds the first occurrence of a wide string within another wide string (function) |
|
finds the first occurrence of a character (function) |
|
finds the first occurrence of a wide character in a wide string (function) |
|
find the last occurrence of a substring (public member function) |
|
find first occurrence of characters (public member function) |
|
find first absence of characters (public member function) |
|
find last occurrence of characters (public member function) |
|
find last absence of characters (public member function) |
|
searches for a range of elements (function template) |
© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
http://en.cppreference.com/w/cpp/string/basic_string/find