std::find,s...:find_if_not(3)

💅 std::find,s...:find_if_not(3) 💅

okay so bestie, this is a page from the C++ Standard Libary manual (yes, that spelling is literally in the header, no cap). It’s section 3, and the full cast is in the NAME below. 💖

---

🌸 NAME 🌸

std::find, std::find_if, std::find_if_not — std::find,std::find_if,std::find_if_not

✨ Synopsis ✨

Defined in header <algorithm>

(1) — find, InputIt overload:

template< class InputIt, class T >
InputIt find( InputIt first, InputIt last, const T& value );

(constexpr since C++20) (until C++26)

template< class InputIt, class T = typename std::iterator_traits<InputIt>::value_type >
constexpr InputIt find( InputIt first, InputIt last, const T& value );

(since C++26)

(2) — find, ExecutionPolicy overload:

template< class ExecutionPolicy, class ForwardIt, class T >
ForwardIt find( ExecutionPolicy&& policy, ForwardIt first, ForwardIt last, const T& value );

(since C++17) (until C++26)

template< class ExecutionPolicy, class ForwardIt, class T = typename std::iterator_traits<ForwardIt>::value_type >
ForwardIt find( ExecutionPolicy&& policy, ForwardIt first, ForwardIt last, const T& value );

(since C++26)

(3) — find_if, InputIt overload:

template< class InputIt, class UnaryPred >
InputIt find_if( InputIt first, InputIt last, UnaryPred p );

(constexpr since C++20)

(4) — find_if, ExecutionPolicy overload:

template< class ExecutionPolicy, class ForwardIt, class UnaryPred >
ForwardIt find_if( ExecutionPolicy&& policy, ForwardIt first, ForwardIt last, UnaryPred p );

(since C++17)

(5) — find_if_not, InputIt overload:

template< class InputIt, class UnaryPred >
InputIt find_if_not( InputIt first, InputIt last, UnaryPred q );

(since C++11) (constexpr since C++20)

(6) — find_if_not, ExecutionPolicy overload:

template< class ExecutionPolicy, class ForwardIt, class UnaryPred >
ForwardIt find_if_not( ExecutionPolicy&& policy, ForwardIt first, ForwardIt last, UnaryPred q );

(since C++17)

Returns an iterator to the first element in the range [first, last) that satisfies specific criteria (or last if there is no such iterator).

• 1) find searches for an element equal to value (using operator==).
• 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 participate in overload resolution only if std::is_execution_policy_v<std::decay_t<ExecutionPolicy>> is true (until C++20), or std::is_execution_policy_v<std::remove_cvref_t<ExecutionPolicy>> is true (since C++20).

🌈 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.
• p — unary predicate which returns true for the required element. The expression p(v) must be convertible to bool for every argument v 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).
• q — unary predicate which returns false for the required element. The expression q(v) must be convertible to bool for every argument v 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 🎀

The first iterator it in the range [first, last) satisfying the following condition, or last if there is no such iterator:

• 1,2) *it == value is true.
• 3,4) p(*it) is true.
• 5,6) q(*it) is false.

🔥 Complexity 🔥

Given N as std::distance(first, last):

• 1,2) At most N comparisons with value using operator==.
• 3,4) At most N applications of the predicate p.
• 5,6) At most N applications of the predicate q.

💀 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 👑

find

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

    return last;
}

find_if

template<class InputIt, class UnaryPred>
constexpr InputIt find_if(InputIt first, InputIt last, UnaryPred p)
{
    for (; first != last; ++first)
        if (p(*first))
            return first;

    return last;
}

find_if_not

template<class InputIt, class UnaryPred>
constexpr InputIt find_if_not(InputIt first, InputIt last, UnaryPred q)
{
    for (; first != last; ++first)
        if (!q(*first))
            return first;

    return last;
}

💜 Notes 💜

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

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

Feature-test macro:

• __cpp_lib_algorithm_default_value_type — value 202403 (C++26), feature: List-initialization for algorithms (1,2).

🌟 Example 🌟

The following example finds numbers in given sequences.

// Run this code

#include <algorithm>
#include <array>
#include <cassert>
#include <complex>
#include <iostream>
#include <vector>

int main()
{
    const auto v = {1, 2, 3, 4};

    for (const int n : {3, 5})
        (std::find(v.begin(), v.end(), n) == std::end(v))
            ? std::cout << "v does not contain " << n << '\n'
            : std::cout << "v contains " << n << '\n';

    auto is_even = [](int i) { return i % 2 == 0; };

    for (const auto& w : {std::array{3, 1, 4}, {1, 3, 5}})
        if (auto it = std::find_if(begin(w), end(w), is_even); it != std::end(w))
            std::cout << "w contains an even number " << *it << '\n';
        else
            std::cout << "w does not contain even numbers\n";

    std::vector<std::complex<double>> nums{{4, 2}};
    #ifdef __cpp_lib_algorithm_default_value_type
        // T gets deduced making list-initialization possible
        const auto it = std::find(nums.begin(), nums.end(), {4, 2});
    #else
        const auto it = std::find(nums.begin(), nums.end(),
                                  std::complex<double>{4, 2});
    #endif
    assert(it == nums.begin());
}

🍓 Output 🍓

v contains 3
v does not contain 5
w contains an even number 4
w does not contain even numbers

💎 Defect reports 💎

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• DR LWG 283, applied to C++98.
  • Behavior as published: T was required to be EqualityComparable, but the value type of InputIt might not be T.
  • Correct behavior: removed the requirement.

🫶 See also 🫶

• adjacent_find — finds the first two adjacent items that are equal (or satisfy a 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)

---

that’s the whole page, bestie — source http://cppreference.com, version/date 2024.06.10, page id std::find,s...:find_if_not(3). mwah 💋✨