On this page
std::search
Defined in header <algorithm> |
||
|---|---|---|
| (1) | ||
|
(until C++20) | |
|
(since C++20) | |
|
(2) | (since C++17) |
| (3) | ||
|
(until C++20) | |
|
(since C++20) | |
|
(4) | (since C++17) |
| (5) | ||
|
(since C++17) (until C++20) |
|
|
(since C++20) |
[s_first, s_last) in the range [first, last).
operator==.
p.
policy. These overloads do not participate in overload resolution unless
|
(until C++20) |
|
(since C++20) |
[first, last) for the pattern specified in the constructor of searcher. Searcher need not be CopyConstructible.
The standard library provides the following searchers:
|
(since C++17) |
Parameters
| first, last | - | the range of elements to examine |
| s_first, s_last | - | the range of elements to search for |
| policy | - | the execution policy to use. See execution policy for details. |
| searcher | - | the searcher encapsulating the search algorithm and the pattern to look for |
| p | - | binary predicate which returns true if the elements should be treated as equal. The signature of the predicate function should be equivalent to the following:
While the signature does not need to have |
| Type requirements | ||
-ForwardIt1, ForwardIt2 must meet the requirements of LegacyForwardIterator. |
||
Return value
[s_first, s_last) in the range [first, last). If no such occurrence is found, last is returned.
[s_first, s_last) is empty, first is returned.
searcher(first, last).first.
Complexity
std::distance(first, last) and \(\scriptsize S\)S as std::distance(s_first, s_last):
operator==.
p.
searcher.
Exceptions
The overloads with a template parameter named ExecutionPolicy report errors as follows:
- If execution of a function invoked as part of the algorithm throws an exception and
ExecutionPolicyis one of the standard policies,std::terminateis called. For any otherExecutionPolicy, the behavior is implementation-defined. - If the algorithm fails to allocate memory,
std::bad_allocis thrown.
Possible implementation
| search (1) |
|---|
|
| search (3) |
|
Example
#include <algorithm>
#include <cassert>
#include <functional>
#include <iomanip>
#include <iostream>
#include <iterator>
#include <string_view>
#include <vector>
using namespace std::literals;
bool contains(const auto& cont, std::string_view s)
{
// str.find() (or str.contains(), since C++23) can be used as well
return std::search(cont.begin(), cont.end(), s.begin(), s.end()) != cont.end();
}
int main()
{
const auto str{"why waste time learning, when ignorance is instantaneous?"sv};
assert(contains(str, "learning"));
assert(not contains(str, "lemming"));
const std::vector vec(str.begin(), str.end());
assert(contains(vec, "learning"));
assert(not contains(vec, "leaning"));
// The C++17 overload with searchers demo:
constexpr auto quote
{
"Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed "
"do eiusmod tempor incididunt ut labore et dolore magna aliqua"sv
};
for (const auto word : {"pisci"sv, "Pisci"sv})
{
std::cout << "The string " << std::quoted(word) << ' ';
const std::boyer_moore_searcher searcher(word.begin(), word.end());
const auto it = std::search(quote.begin(), quote.end(), searcher);
if (it == quote.end())
std::cout << "not found\n";
else
std::cout << "found at offset " << std::distance(quote.begin(), it) << '\n';
}
}
Output:
The string "pisci" found at offset 43
The string "Pisci" not found
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 1205 | C++98 | the return value was unclear if [s_first, s_last) is empty |
returns first in this case |
| LWG 1338 | C++98 | the resolution of LWG issue 1205 was incorrectly applied, making first to be returned if no occurence is found |
returns last in this case |
See also
| finds the last sequence of elements in a certain range (function template) |
|
returns true if one sequence is a subsequence of another (function template) |
|
| determines if two sets of elements are the same (function template) |
|
|
(C++11)
|
finds the first element satisfying specific criteria (function template) |
returns true if one range is lexicographically less than another (function template) |
|
| finds the first position where two ranges differ (function template) |
|
| searches a range for a number of consecutive copies of an element (function template) |
|
|
(C++17)
|
standard C++ library search algorithm implementation (class template) |
|
(C++17)
|
Boyer-Moore search algorithm implementation (class template) |
|
(C++17)
|
Boyer-Moore-Horspool search algorithm implementation (class template) |
|
(C++20)
|
searches for a range of elements (niebloid) |
© cppreference.com
Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.
https://en.cppreference.com/w/cpp/algorithm/search