NAME¶

std::find,std::find_if,std::find_if_not - std::find,std::find_if,std::find_if_not

Synopsis¶

Defined in header <algorithm>
template< class InputIt, class T >
InputIt find( InputIt first, InputIt (until C++20)
last, const T& value );
template< class InputIt, class T >
constexpr InputIt find( InputIt first, (since C++20)
InputIt last, const T& value );
template< class ExecutionPolicy, class
ForwardIt, class T >

ForwardIt find( ExecutionPolicy&& (2) (since C++17)
policy, ForwardIt first, ForwardIt last,

const T& value );
template< class InputIt, class
UnaryPredicate >

InputIt find_if( InputIt first, InputIt (until C++20)
last,

UnaryPredicate p );
template< class InputIt, class
UnaryPredicate >

constexpr InputIt find_if( InputIt (since C++20)
first, InputIt last,

UnaryPredicate p );
template< class ExecutionPolicy, class (1)
ForwardIt, class UnaryPredicate >

ForwardIt find_if( ExecutionPolicy&& (4) (since C++17)
policy, ForwardIt first, ForwardIt last,

UnaryPredicate p ); (3)
template< class InputIt, class
UnaryPredicate > (since
C++11)
InputIt find_if_not( InputIt first, (until
InputIt last, C++20)

UnaryPredicate q );
template< class InputIt, class
UnaryPredicate >
(since
constexpr InputIt find_if_not( InputIt (5) C++20)
first, InputIt last,

UnaryPredicate q );
template< class ExecutionPolicy, class
ForwardIt, class UnaryPredicate >
(since
ForwardIt find_if_not( ExecutionPolicy&& (6) C++17)
policy, ForwardIt first, ForwardIt last,

UnaryPredicate q );

Returns an iterator to the first element in the range [first, last) that satisfies
specific criteria:

1) find searches for an element equal to value
3) find_if searches for an element for which predicate p returns true
5) find_if_not searches for an element for which predicate q returns false
2,4,6) Same as (1,3,5), but executed according to policy. These overloads do not
participate in overload resolution unless
std::is_execution_policy_v<std::decay_t<ExecutionPolicy>>
(until C++20)
std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>>
(since C++20) is true.

Parameters¶

first, last - the range of elements to examine
value - value to compare the elements to
policy - the execution policy to use. See execution policy for details.
unary predicate which returns true for the required element.

The expression p(v) must be convertible to bool for every argument v
p - of type (possibly const) VT, where VT is the value type of InputIt,
regardless of value category, and must not modify v. Thus, a parameter
type of VT&is not allowed
, nor is VT unless for VT a move is equivalent to a copy
(since C++11).
unary predicate which returns false for the required element.

The expression q(v) must be convertible to bool for every argument v
q - of type (possibly const) VT, where VT is the value type of InputIt,
regardless of value category, and must not modify v. Thus, a parameter
type of VT&is not allowed
, nor is VT unless for VT a move is equivalent to a copy
(since C++11).

Type requirements¶

-
InputIt must meet the requirements of LegacyInputIterator.
-
ForwardIt must meet the requirements of LegacyForwardIterator.
-
UnaryPredicate must meet the requirements of Predicate.

Return value¶

Iterator to the first element satisfying the condition or last if no such element is
found.

Complexity¶

At most N applications of the predicate, where N = std::distance(first, last).

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.

Possible implementation¶

First version¶

template<class InputIt, class T>
constexpr InputIt find(InputIt first, InputIt last, const T& value)
{
for (; first != last; ++first) {
if (*first == value) {
return first;
}
}
return last;
}

Second version¶

template<class InputIt, class UnaryPredicate>
constexpr InputIt find_if(InputIt first, InputIt last, UnaryPredicate p)
{
for (; first != last; ++first) {
if (p(*first)) {
return first;
}
}
return last;
}
Third version
template<class InputIt, class UnaryPredicate>
constexpr InputIt find_if_not(InputIt first, InputIt last, UnaryPredicate q)
{
for (; first != last; ++first) {
if (!q(*first)) {
return first;
}
}
return last;
}

Notes¶

If you do not have C++11, an equivalent to std::find_if_not is to use std::find_if
with the negated predicate.

template<class InputIt, class UnaryPredicate>
InputIt find_if_not(InputIt first, InputIt last, UnaryPredicate q)
{
return std::find_if(first, last, std::not1(q));
}

Example¶

The following example finds integers in given vector.

// Run this code

#include <iostream>
#include <algorithm>
#include <vector>
#include <iterator>

int main()
{
std::vector<int> v{1, 2, 3, 4};
int n1 = 3;
int n2 = 5;
auto is_even = [](int i){ return i%2 == 0; };

auto result1 = std::find(begin(v), end(v), n1);
auto result2 = std::find(begin(v), end(v), n2);
auto result3 = std::find_if(begin(v), end(v), is_even);

(result1 != std::end(v))
? std::cout << "v contains " << n1 << '\n'
: std::cout << "v does not contain " << n1 << '\n';

(result2 != std::end(v))
? std::cout << "v contains " << n2 << '\n'
: std::cout << "v does not contain " << n2 << '\n';

(result3 != std::end(v))
? std::cout << "v contains an even number: " << *result3 << '\n'
: std::cout << "v does not contain even numbers\n";
}

Output:¶

v contains 3
v does not contain 5
v contains an even number: 2

See also¶

finds the first two adjacent items that are equal (or satisfy a
adjacent_find given predicate)
(function template)
find_end finds the last sequence of elements in a certain range
(function template)
find_first_of searches for any one of a set of elements
(function template)
mismatch finds the first position where two ranges differ
(function template)
search searches for a range of elements
(function template)
ranges::find
ranges::find_if
ranges::find_if_not finds the first element satisfying specific criteria
(C++20) (niebloid)
(C++20)
(C++20)