Difference between revisions of "cpp/algorithm/find first of"

Latest revision as of 21:44, 19 March 2024

Defined in header `<algorithm>`
template< class InputIt, class ForwardIt > InputIt find_first_of( InputIt first, InputIt last, ForwardIt s_first, ForwardIt s_last );	(1)	(constexpr since C++20)
template< class ExecutionPolicy, class ForwardIt1, class ForwardIt2 > ForwardIt1 find_first_of( ExecutionPolicy&& policy, ForwardIt1 first, ForwardIt1 last, ForwardIt2 s_first, ForwardIt2 s_last );	(2)	(since C++17)
template< class InputIt, class ForwardIt, class BinaryPred > InputIt find_first_of( InputIt first, InputIt last, ForwardIt s_first, ForwardIt s_last, BinaryPred p );	(3)	(constexpr since C++20)
template< class ExecutionPolicy, class ForwardIt1, class ForwardIt2, class BinaryPred > ForwardIt1 find_first_of( ExecutionPolicy&& policy, ForwardIt1 first, ForwardIt last, ForwardIt2 s_first, ForwardIt2 s_last, BinaryPred p );	(4)	(since C++17)

Searches the range [first, last) for any of the elements in the range [s_first, s_last).

1) Elements are compared using operator==.

3) Elements are compared using the given binary predicate p.

2,4) Same as (1,3), but executed according to policy.

These overloads participate in overload resolution only if

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	-	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.
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) `Type1` and `Type2` regardless of value category (thus, Type1 & is not allowed, nor is Type1 unless for `Type1` a move is equivalent to a copy(since C++11)). The types Type1 and Type2 must be such that objects of types ForwardIt1 and ForwardIt2 can be dereferenced and then implicitly converted to Type1 and Type2 respectively.
Type requirements
- `InputIt` must meet the requirements of LegacyInputIterator.
- `ForwardIt` must meet the requirements of LegacyForwardIterator.
- `ForwardIt1` must meet the requirements of LegacyForwardIterator.
- `ForwardIt2` must meet the requirements of LegacyForwardIterator.
- `BinaryPred` must meet the requirements of BinaryPredicate.

[edit] Return value

Iterator to the first element in the range [first, last) that is equal to an element from the range [s_first, s_last).

If [s_first, s_last) is empty or if no such element is found, last is returned.

[edit] Complexity

Given $\scriptsize N$ $N$ as std::distance(first, last) and $\scriptsize S$ $S$ as std::distance(s_first, s_last):

1,2) At most

N\cdotS

comparisons using operator==.

3,4) At most

N\cdotS

applications of the predicate p.

[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 other ExecutionPolicy, the behavior is implementation-defined.
If the algorithm fails to allocate memory, std::bad_alloc is thrown.

[edit] Possible implementation

find_first_of (1)

template<class InputIt, class ForwardIt>
InputIt find_first_of(InputIt first, InputIt last,
                      ForwardIt s_first, ForwardIt s_last)
{
    for (; first != last; ++first)
        for (ForwardIt it = s_first; it != s_last; ++it)
            if (*first == *it)
                return first;
    return last;
}

find_first_of (3)

template<class InputIt, class ForwardIt, class BinaryPred>
InputIt find_first_of(InputIt first, InputIt last,
                      ForwardIt s_first, ForwardIt s_last,
                      BinaryPred p)
{
    for (; first != last; ++first)
        for (ForwardIt it = s_first; it != s_last; ++it)
            if (p(*first, *it))
                return first;
    return last;
}

[edit] Example

The following code searches for any of specified integers in a vector of integers:

Run this code

#include <algorithm>
#include <iostream>
#include <vector>
 
auto print_sequence = [](const auto id, const auto& seq, int pos = -1)
{
    std::cout << id << "{ ";
    for (int i{}; auto const& e : seq)
    {
        const bool mark{i == pos};
        std::cout << (i++ ? ", " : "");
        std::cout << (mark ? "[ " : "") << e << (mark ? " ]" : "");
    }
    std::cout << " }\n";
};
 
int main()
{
    const std::vector<int> v{0, 2, 3, 25, 5};
    const auto t1 = {19, 10, 3, 4};
    const auto t2 = {1, 6, 7, 9};
 
    auto find_any_of = [](const auto& v, const auto& t)
    {
        const auto result = std::find_first_of(v.begin(), v.end(),
                                               t.begin(), t.end());
        if (result == v.end())
        {
            std::cout << "No elements of v are equal to any element of ";
            print_sequence("t = ", t);
            print_sequence("v = ", v);
        }
        else
        {
            const auto pos = std::distance(v.begin(), result);
            std::cout << "Found a match (" << *result << ") at position " << pos;
            print_sequence(", where t = ", t);
            print_sequence("v = ", v, pos);
        }
    };
 
    find_any_of(v, t1);
    find_any_of(v, t2);
}

Output:

Found a match (3) at position 2, where t = { 19, 10, 3, 4 }
v = { 0, 2, [ 3 ], 25, 5 }
No elements of v are equal to any element of t = { 1, 6, 7, 9 }
v = { 0, 2, 3, 25, 5 }

[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 576	C++98	first and last needed to be LegacyForwardIterators	they only need to be LegacyInputIterators
LWG 1205	C++98	the return value was unclear if `[`s_first`,` s_last`)` is empty	returns last in this case

[edit] See also

findfind_iffind_if_not (C++11)	finds the first element satisfying specific criteria (function template) [edit]
ranges::find_first_of (C++20)	searches for any one of a set of elements (niebloid)[edit]

@@ Line 2: / Line 2: @@
 {{cpp/algorithm/navbar}}
 {{dcl begin}}
-{{dcl header | algorithm}}
+{{dcl header|algorithm}}
-{{dcl rev begin | num=1}}
+{{dcla|num=1|notes={{mark constexpr since c++20}}|
-{{dcl | since= | until=c++11 | num= |1=
-template< class ForwardIt1, class ForwardIt2 >
-ForwardIt1 find_first_of( ForwardIt1 first, ForwardIt1 last,
-                          ForwardIt2 s_first, ForwardIt2 s_last );
-}}
-{{dcl|since=c++11|until=c++20|1=
 template< class InputIt, class ForwardIt >
 InputIt find_first_of( InputIt first, InputIt last,
                         ForwardIt s_first, ForwardIt s_last );
 }}
-{{dcl|since=c++20|1=
+{{dcl|num=2|since=c++17|
-template< class InputIt, class ForwardIt >
-constexpr InputIt find_first_of( InputIt first, InputIt last,
-                                 ForwardIt s_first, ForwardIt s_last );
-}}
-{{dcl rev end}}
-{{dcl | since=c++17 | until= | num=2 |1=
 template< class ExecutionPolicy, class ForwardIt1, class ForwardIt2 >
-ForwardIt1 find_first_of( ExecutionPolicy&& policy, ForwardIt1 first, ForwardIt1 last,
+ForwardIt1 find_first_of( ExecutionPolicy&& policy,
-                       ForwardIt2 s_first, ForwardIt2 s_last );
+                          ForwardIt1 first, ForwardIt1 last,
-}}
+                           ForwardIt2 s_first, ForwardIt2 s_last );
-{{dcl rev begin | num=3}}
-{{dcl | since= | until=c++11 | num= |1=
-template< class ForwardIt1, class ForwardIt2, class BinaryPredicate >
-ForwardIt1 find_first_of( ForwardIt1 first, ForwardIt1 last,
-                           ForwardIt2 s_first, ForwardIt2 s_last, BinaryPredicate p );
 }}
-{{dcl|since=c++11|until=c++20|1=
+{{dcla|num=3|notes={{mark constexpr since c++20}}|
-template< class InputIt, class ForwardIt, class BinaryPredicate >
+template< class InputIt, class ForwardIt, class BinaryPred >
 InputIt find_first_of( InputIt first, InputIt last,
-                        ForwardIt s_first, ForwardIt s_last, BinaryPredicate p );
+                        ForwardIt s_first, ForwardIt s_last,
+                       BinaryPred p );
 }}
-{{dcl|since=c++20|1=
+{{dcl|num=4|since=c++17|
-template< class InputIt, class ForwardIt, class BinaryPredicate >
+template< class ExecutionPolicy,
-constexpr InputIt find_first_of( InputIt first, InputIt last,
+          class ForwardIt1, class ForwardIt2, class BinaryPred >
-                                 ForwardIt s_first, ForwardIt s_last, BinaryPredicate p );
+ForwardIt1 find_first_of( ExecutionPolicy&& policy,
-}}
+                          ForwardIt1 first, ForwardIt last,
-{{dcl rev end}}
+                          ForwardIt2 s_first, ForwardIt2 s_last,
-{{dcl | since=c++17 | until= | num=4 |1=
+                          BinaryPred p );
-template< class ExecutionPolicy, class ForwardIt1, class ForwardIt2, class BinaryPredicate >
-ForwardIt1 find_first_of( ExecutionPolicy&& policy, ForwardIt1 first, ForwardIt last,
-                       ForwardIt2 s_first, ForwardIt2 s_last, BinaryPredicate p );
 }}
 {{dcl end}}
-Searches the range {{tt|[first, last)}} for any of the elements in the range {{tt|[s_first, s_last)}}.
+Searches the range {{range|first|last}} for any of the elements in the range {{range|s_first|s_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}}
-@1@ Elements are compared using {{tt|operator{{==}}}}.
-@3@ Elements are compared using the given binary predicate {{tt|p}}.
-@2,4@ Same as {{v|1,3}}, but executed according to {{tt|policy}}. {{cpp/algorithm/parallel overload precondition|plural=true}}
 ===Parameters===
 {{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 exec pol}}
-{{par pred2 eq | p | p1=ForwardIt1 | p2=ForwardIt2}}
+{{par pred2 eq|p|p1=ForwardIt1|p2=ForwardIt2}}
 {{par hreq}}
-{{par req named | InputIt | InputIterator}}
+{{par req named|InputIt|InputIterator}}
-{{par req named | ForwardIt1 | ForwardIterator}}
+{{par req named|ForwardIt|ForwardIterator}}
-{{par req named | ForwardIt2 | ForwardIterator}}
+{{par req named|ForwardIt1|ForwardIterator}}
+{{par req named|ForwardIt2|ForwardIterator}}
+{{par req named|BinaryPred|BinaryPredicate}}
 {{par end}}
 ===Return value===
-Iterator to the first element in the range {{tt|[first, last)}} that is equal to an element from the range {{tt|[s_first, s_last)}}. If no such element is found, {{tt|last}} is returned.
+Iterator to the first element in the range {{range|first|last}} that is equal to an element from the range {{range|s_first|s_last}}.
+If {{range|s_first|s_last}} is empty or if no such element is found, {{c|last}} is returned.
 ===Complexity===
-Does at most {{tt|(S*N)}} comparisons where {{c|1=S = std::distance(s_first, s_last)}} and {{c|1=N = std::distance(first, last)}}.
+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&middot;S}} comparisons using {{c/core|1=operator==}}.
+@3,4@ At most {{mathjax-or|\(\scriptsize N\cdot S\)|N&middot;S}} applications of the predicate {{c|p}}.
 ===Exceptions===
-{{cpp/algorithm/parallel_exceptions_reporting_behavior|singular=no}}
+{{cpp/algorithm/parallel exceptions reporting behavior|singular=no}}
 ===Possible implementation===
-{{eq fun
+{{eq impl
- | 1=
+|title1=find_first_of (1)|ver1=1|1=
 template<class InputIt, class ForwardIt>
 InputIt find_first_of(InputIt first, InputIt last,
                        ForwardIt s_first, ForwardIt s_last)
 {
-     for (; first != last; ++first) {
+     for (; first != last; ++first)
-         for (ForwardIt it = s_first; it != s_last; ++it) {
+         for (ForwardIt it = s_first; it != s_last; ++it)
-             if (*first == *it) {
+             if (*first == *it)
                  return first;
-            }
-        }
-    }
      return last;
 }
- | 2=
+|title2=find_first_of (3)|ver2=3|2=
-template<class InputIt, class ForwardIt, class BinaryPredicate>
+template<class InputIt, class ForwardIt, class BinaryPred>
 InputIt find_first_of(InputIt first, InputIt last,
                        ForwardIt s_first, ForwardIt s_last,
-                       BinaryPredicate p)
+                       BinaryPred p)
 {
-     for (; first != last; ++first) {
+     for (; first != last; ++first)
-         for (ForwardIt it = s_first; it != s_last; ++it) {
+         for (ForwardIt it = s_first; it != s_last; ++it)
-             if (p(*first, *it)) {
+             if (p(*first, *it))
                  return first;
-            }
-        }
-    }
      return last;
 }
@@ Line 113: / Line 95: @@
 ===Example===
 {{example
- | The following code searches for any of specified integers in a vector of integers:
+|The following code searches for any of specified integers in a vector of integers:
- | code=
+|code=
 #include <algorithm>
 #include <iostream>
 #include <vector>
+auto print_sequence = [](const auto id, const auto& seq, int pos = -1)
+{
+    std::cout << id << "{ ";
+    for (int i{}; auto const& e : seq)
+    {
+        const bool mark{i == pos};
+        std::cout << (i++ ? ", " : "");
+        std::cout << (mark ? "[ " : "") << e << (mark ? " ]" : "");
+    }
+    std::cout << " }\n";
+};
 int main()
 {
-     std::vector<int> v{0, 2, 3, 25, 5}, t = {3, 19, 10, 2};
+     const std::vector<int> v{0, 2, 3, 25, 5};
+    const auto t1 = {19, 10, 3, 4};
-     auto result = std::find_first_of(v.begin(), v.end(), t.begin(), t.end());
+    const auto t2 = {1, 6, 7, 9};
-    if (result == v.end()) {
+    auto find_any_of = [](const auto& v, const auto& t)
-         std::cout << "no elements of v were equal to 3, 19, 10 or 2\n";
+    {
-    } else {
+        const auto result = std::find_first_of(v.begin(), v.end(),
-         std::cout << "found a match at "
+                                               t.begin(), t.end());
-                  << std::distance(v.begin(), result) << "\n";
+        if (result == v.end())
-     }
+         {
- }
+            std::cout << "No elements of v are equal to any element of ";
- | output=
+            print_sequence("t = ", t);
-found a match at 1
+            print_sequence("v = ", v);
+        }
+        else
+         {
+            const auto pos = std::distance(v.begin(), result);
+            std::cout << "Found a match (" << *result << ") at position " << pos;
+            print_sequence(", where t = ", t);
+            print_sequence("v = ", v, pos);
+        }
+     };
+    find_any_of(v, t1);
+    find_any_of(v, t2);
+}
+|output=
+Found a match (3) at position 2, where t = { 19, 10, 3, 4 }
+v = { 0, 2, [ 3 ], 25, 5 }
+No elements of v are equal to any element of t = { 1, 6, 7, 9 }
+v = { 0, 2, 3, 25, 5 }
 }}
+===Defect reports===
+{{dr list begin}}
+{{dr list item|wg=lwg|dr=576|std=C++98|before={{c|first}} and {{c|last}} needed to be {{named req|ForwardIterator}}s|after=they only need to be<br>{{named req|InputIterator}}s}}
+{{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|last}} in this case}}
+{{dr list end}}
 ===See also===
 {{dsc begin}}
-{{dsc inc | cpp/algorithm/dsc find}}
+{{dsc inc|cpp/algorithm/dsc find}}
-{{dsc inc | cpp/algorithm/ranges/dsc find_first_of}}
+{{dsc inc|cpp/algorithm/ranges/dsc find_first_of}}
 {{dsc end}}
 {{langlinks|de|es|fr|it|ja|pt|ru|zh}}

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

cppreference.com

Namespaces

Variants

Views

Actions

Difference between revisions of "cpp/algorithm/find first of"

Latest revision as of 21:44, 19 March 2024

Contents

[edit] Parameters