Difference between revisions of "cpp/algorithm/search"
m (+seealso std::experimental::search) |
m (Added the BinaryPredicate requirement.) |
||
(44 intermediate revisions by 14 users not shown) | |||
Line 2: | Line 2: | ||
{{cpp/algorithm/navbar}} | {{cpp/algorithm/navbar}} | ||
{{dcl begin}} | {{dcl begin}} | ||
− | {{dcl header | algorithm}} | + | {{dcl header|algorithm}} |
− | {{ | + | {{dcla|num=1|notes={{mark constexpr since c++20}}| |
template< class ForwardIt1, class ForwardIt2 > | template< class ForwardIt1, class ForwardIt2 > | ||
ForwardIt1 search( ForwardIt1 first, ForwardIt1 last, | ForwardIt1 search( ForwardIt1 first, ForwardIt1 last, | ||
ForwardIt2 s_first, ForwardIt2 s_last ); | ForwardIt2 s_first, ForwardIt2 s_last ); | ||
}} | }} | ||
− | {{dcl | num=2 | | + | {{dcl|num=2|since=c++17| |
− | template< class ForwardIt1, class ForwardIt2, class | + | template< class ExecutionPolicy, class ForwardIt1, class ForwardIt2 > |
+ | ForwardIt1 search( ExecutionPolicy&& policy, | ||
+ | ForwardIt1 first, ForwardIt1 last, | ||
+ | ForwardIt2 s_first, ForwardIt2 s_last ); | ||
+ | }} | ||
+ | {{dcla|num=3|notes={{mark constexpr since c++20}}| | ||
+ | template< class ForwardIt1, class ForwardIt2, class BinaryPred > | ||
ForwardIt1 search( ForwardIt1 first, ForwardIt1 last, | ForwardIt1 search( ForwardIt1 first, ForwardIt1 last, | ||
− | ForwardIt2 s_first, ForwardIt2 s_last, | + | ForwardIt2 s_first, ForwardIt2 s_last, |
+ | BinaryPred p ); | ||
+ | }} | ||
+ | {{dcl|num=4|since=c++17| | ||
+ | template< class ExecutionPolicy, | ||
+ | class ForwardIt1, class ForwardIt2, class BinaryPred > | ||
+ | ForwardIt1 search( ExecutionPolicy&& policy, | ||
+ | ForwardIt1 first, ForwardIt1 last, | ||
+ | ForwardIt2 s_first, ForwardIt2 s_last, | ||
+ | BinaryPred p ); | ||
+ | }} | ||
+ | {{dcl|num=5|since=c++17|notes={{mark constexpr since c++20}}| | ||
+ | template< class ForwardIt, class Searcher > | ||
+ | ForwardIt search( ForwardIt first, ForwardIt last, | ||
+ | const Searcher& searcher ); | ||
}} | }} | ||
{{dcl end}} | {{dcl end}} | ||
− | Searches for the first occurrence of the | + | @1-4@ Searches for the first occurrence of the sequence of elements {{range|s_first|s_last}} in the range {{range|first|last}}. |
+ | :@1@ Elements are compared using {{c/core|1=operator==}}. | ||
+ | :@3@ Elements are compared using the given binary predicate {{c|p}}. | ||
+ | :@2,4@ Same as {{v|1,3}}, but executed according to {{c|policy}}. | ||
+ | :@@ {{cpp/algorithm/parallel overload precondition|plural=yes}} | ||
+ | |||
+ | @5@ Searches the range {{range|first|last}} for the pattern specified in the constructor of {{c|searcher}}. | ||
+ | |||
+ | {{rrev|since=c++17| | ||
+ | The standard library provides the following searchers: | ||
+ | {{dsc begin}} | ||
+ | {{dsc inc|cpp/utility/functional/dsc default_searcher}} | ||
+ | {{dsc inc|cpp/utility/functional/dsc boyer_moore_searcher}} | ||
+ | {{dsc inc|cpp/utility/functional/dsc boyer_moore_horspool_searcher}} | ||
+ | {{dsc end}} | ||
+ | }} | ||
===Parameters=== | ===Parameters=== | ||
{{par begin}} | {{par begin}} | ||
− | {{par | first, last | the range of elements to examine}} | + | {{par|first, last|the range of elements to examine}} |
− | {{par | s_first, s_last | the range of elements to search for}} | + | {{par|s_first, s_last|the range of elements to search for}} |
− | {{par pred2 eq | p | p1=ForwardIt1 | p2=ForwardIt2}} | + | {{par exec pol}} |
+ | {{par|searcher|the searcher encapsulating the search algorithm and the pattern to look for}} | ||
+ | {{par pred2 eq|p|p1=ForwardIt1|p2=ForwardIt2}} | ||
{{par hreq}} | {{par hreq}} | ||
− | {{par req | + | {{par req named|ForwardIt1, ForwardIt2|ForwardIterator}} |
+ | {{par req named|BinaryPred|BinaryPredicate}} | ||
{{par end}} | {{par end}} | ||
===Return value=== | ===Return value=== | ||
− | Iterator to the beginning of first | + | @1-4@ Iterator to the beginning of first occurrence of the sequence {{range|s_first|s_last}} in the range {{range|first|last}}. If no such occurrence is found, {{c|last}} is returned. |
− | If {{ | + | @@ If {{range|s_first|s_last}} is empty, {{c|first}} is returned. |
+ | |||
+ | @5@ {{c|searcher(first, last).first}}. | ||
===Complexity=== | ===Complexity=== | ||
− | + | @1-4@ Given {{mathjax-or|\(\scriptsize N\)|N}} as {{c|std::distance(first, last)}} and {{mathjax-or|\(\scriptsize S\)|S}} as {{c|std::distance(s_first, s_last)}}: | |
+ | :@1,2@ At most {{mathjax-or|\(\scriptsize N\cdot S\)|N·S}} comparisons using {{c/core|1=operator==}}. | ||
+ | :@3,4@ At most {{mathjax-or|\(\scriptsize N\cdot S\)|N·S}} applications of the predicate {{c|p}}. | ||
+ | @5@ Depends on {{c|searcher}}. | ||
− | === | + | ===Exceptions=== |
+ | {{cpp/algorithm/parallel exceptions reporting behavior|singular=no}} | ||
− | {{eq | + | ===Possible implementation=== |
+ | {{eq impl | ||
+ | |title1=search (1)|ver1=1|1= | ||
template<class ForwardIt1, class ForwardIt2> | template<class ForwardIt1, class ForwardIt2> | ||
+ | constexpr //< since C++20 | ||
ForwardIt1 search(ForwardIt1 first, ForwardIt1 last, | ForwardIt1 search(ForwardIt1 first, ForwardIt1 last, | ||
− | + | ForwardIt2 s_first, ForwardIt2 s_last) | |
{ | { | ||
− | + | while (true) | |
+ | { | ||
ForwardIt1 it = first; | ForwardIt1 it = first; | ||
− | for (ForwardIt2 s_it = s_first; ; ++it, ++s_it) { | + | for (ForwardIt2 s_it = s_first; ; ++it, ++s_it) |
− | if (s_it == s_last) | + | { |
+ | if (s_it == s_last) | ||
return first; | return first; | ||
− | + | if (it == last) | |
− | if (it == last) | + | |
return last; | return last; | ||
− | + | if (!(*it == *s_it)) | |
− | if (!(*it == *s_it)) | + | |
break; | break; | ||
− | |||
} | } | ||
+ | ++first; | ||
} | } | ||
} | } | ||
− | + | |title2=search (3)|ver2=3|2= | |
− | template<class ForwardIt1, class ForwardIt2, class | + | template<class ForwardIt1, class ForwardIt2, class BinaryPred> |
+ | constexpr //< since C++20 | ||
ForwardIt1 search(ForwardIt1 first, ForwardIt1 last, | ForwardIt1 search(ForwardIt1 first, ForwardIt1 last, | ||
− | + | ForwardIt2 s_first, ForwardIt2 s_last, BinaryPred p) | |
− | + | ||
{ | { | ||
− | + | while (true) | |
+ | { | ||
ForwardIt1 it = first; | ForwardIt1 it = first; | ||
− | for (ForwardIt2 s_it = s_first; ; ++it, ++s_it) { | + | for (ForwardIt2 s_it = s_first; ; ++it, ++s_it) |
− | if (s_it == s_last) | + | { |
+ | if (s_it == s_last) | ||
return first; | return first; | ||
− | + | if (it == last) | |
− | if (it == last) | + | |
return last; | return last; | ||
− | + | if (!p(*it, *s_it)) | |
− | if (!p(*it, *s_it)) | + | |
break; | break; | ||
− | |||
} | } | ||
+ | ++first; | ||
} | } | ||
} | } | ||
Line 79: | Line 126: | ||
===Example=== | ===Example=== | ||
− | {{example | + | {{example |
|code= | |code= | ||
− | |||
#include <algorithm> | #include <algorithm> | ||
+ | #include <cassert> | ||
+ | #include <functional> | ||
+ | #include <iomanip> | ||
#include <iostream> | #include <iostream> | ||
+ | #include <iterator> | ||
+ | #include <string_view> | ||
#include <vector> | #include <vector> | ||
− | + | using namespace std::literals; | |
− | bool | + | |
+ | 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(); | return std::search(cont.begin(), cont.end(), s.begin(), s.end()) != cont.end(); | ||
} | } | ||
Line 94: | Line 147: | ||
int main() | 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()); | |
− | std::vector | + | assert(contains(vec, "learning")); |
− | std::cout << std:: | + | 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= | |output= | ||
− | + | The string "pisci" found at offset 43 | |
− | + | The string "Pisci" not found | |
− | + | ||
− | + | ||
}} | }} | ||
+ | |||
+ | ===Defect reports=== | ||
+ | {{dr list begin}} | ||
+ | {{dr list item|wg=lwg|dr=1205|std=C++98|before=the return value was unclear if {{range|s_first|s_last}} is empty|after=returns {{c|first}} in this case}} | ||
+ | {{dr list item|wg=lwg|dr=1338|std=C++98|before=the resolution of {{lwg|1205}} was incorrectly applied,<br>making {{c|first}} to be returned if no occurence is found|after=returns {{c|last}} in this case}} | ||
+ | {{dr list item|wg=lwg|dr=2150|std=C++98|before=the condition of “sequence occurence” was incorrect|after=corrected}} | ||
+ | {{dr list end}} | ||
===See also=== | ===See also=== | ||
{{dsc begin}} | {{dsc begin}} | ||
− | {{dsc inc | cpp/algorithm/dsc find_end}} | + | {{dsc inc|cpp/algorithm/dsc find_end}} |
− | {{dsc inc | cpp/algorithm/dsc includes}} | + | {{dsc inc|cpp/algorithm/dsc includes}} |
− | {{dsc inc | cpp/algorithm/dsc equal}} | + | {{dsc inc|cpp/algorithm/dsc equal}} |
− | {{dsc inc | cpp/algorithm/dsc find}} | + | {{dsc inc|cpp/algorithm/dsc find}} |
− | {{dsc inc | cpp/algorithm/dsc lexicographical_compare}} | + | {{dsc inc|cpp/algorithm/dsc lexicographical_compare}} |
− | {{dsc inc | cpp/algorithm/dsc mismatch}} | + | {{dsc inc|cpp/algorithm/dsc mismatch}} |
− | {{dsc inc | cpp/algorithm/dsc search_n}} | + | {{dsc inc|cpp/algorithm/dsc search_n}} |
− | {{dsc | + | {{dsc inc|cpp/utility/functional/dsc default_searcher}} |
+ | {{dsc inc|cpp/utility/functional/dsc boyer_moore_searcher}} | ||
+ | {{dsc inc|cpp/utility/functional/dsc boyer_moore_horspool_searcher}} | ||
+ | {{dsc inc|cpp/algorithm/ranges/dsc search}} | ||
{{dsc end}} | {{dsc end}} | ||
− | + | {{langlinks|de|es|fr|it|ja|pt|ru|zh}} | |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + |
Latest revision as of 21:46, 25 March 2024
Defined in header <algorithm>
|
||
template< class ForwardIt1, class ForwardIt2 > ForwardIt1 search( ForwardIt1 first, ForwardIt1 last, |
(1) | (constexpr since C++20) |
template< class ExecutionPolicy, class ForwardIt1, class ForwardIt2 > ForwardIt1 search( ExecutionPolicy&& policy, |
(2) | (since C++17) |
template< class ForwardIt1, class ForwardIt2, class BinaryPred > ForwardIt1 search( ForwardIt1 first, ForwardIt1 last, |
(3) | (constexpr since C++20) |
template< class ExecutionPolicy, class ForwardIt1, class ForwardIt2, class BinaryPred > |
(4) | (since C++17) |
template< class ForwardIt, class Searcher > ForwardIt search( ForwardIt first, ForwardIt last, |
(5) | (since C++17) (constexpr since C++20) |
[
s_first,
s_last)
in the range [
first,
last)
.
std::is_execution_policy_v<std::decay_t<ExecutionPolicy>> is true. |
(until C++20) |
std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>> is true. |
(since C++20) |
[
first,
last)
for the pattern specified in the constructor of searcher.
The standard library provides the following searchers:
|
(since C++17) |
Contents |
[edit] 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: bool pred(const Type1 &a, const Type2 &b); While the signature does not need to have const &, the function must not modify the objects passed to it and must be able to accept all values of type (possibly const) |
Type requirements | ||
-ForwardIt1, ForwardIt2 must meet the requirements of LegacyForwardIterator.
| ||
-BinaryPred must meet the requirements of BinaryPredicate.
|
[edit] 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.[edit] Complexity
[edit] 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
ExecutionPolicy
is one of the standard policies, std::terminate is called. For any otherExecutionPolicy
, the behavior is implementation-defined. - If the algorithm fails to allocate memory, std::bad_alloc is thrown.
[edit] Possible implementation
search (1) |
---|
template<class ForwardIt1, class ForwardIt2> constexpr //< since C++20 ForwardIt1 search(ForwardIt1 first, ForwardIt1 last, ForwardIt2 s_first, ForwardIt2 s_last) { while (true) { ForwardIt1 it = first; for (ForwardIt2 s_it = s_first; ; ++it, ++s_it) { if (s_it == s_last) return first; if (it == last) return last; if (!(*it == *s_it)) break; } ++first; } } |
search (3) |
template<class ForwardIt1, class ForwardIt2, class BinaryPred> constexpr //< since C++20 ForwardIt1 search(ForwardIt1 first, ForwardIt1 last, ForwardIt2 s_first, ForwardIt2 s_last, BinaryPred p) { while (true) { ForwardIt1 it = first; for (ForwardIt2 s_it = s_first; ; ++it, ++s_it) { if (s_it == s_last) return first; if (it == last) return last; if (!p(*it, *s_it)) break; } ++first; } } |
[edit] 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
[edit] 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 |
LWG 2150 | C++98 | the condition of “sequence occurence” was incorrect | corrected |
[edit] 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 for the first occurrence of a number consecutive copies of an element in a range (function template) | |
(C++17) |
standard C++ library search algorithm implementation (class template) |
(C++17) |
Boyer-Moore search algorithm implementation (class template) |
Boyer-Moore-Horspool search algorithm implementation (class template) | |
(C++20) |
searches for the first occurrence of a range of elements (niebloid) |