std::min_element(3)

💖 std::min_element — NAME 💖

okay so this page is std::min_element(3), straight out of the C++ Standard Library manual, and bestie it is literally the "find me the smallest thing in this range" function. that's the whole vibe. periodt.

---

✨ Synopsis ✨

girl. look at this. four whole overloads. it's giving main character energy:

Defined in header <algorithm>

template< class ForwardIt >
ForwardIt min_element( ForwardIt first, ForwardIt last );           (1) (constexpr since C++17)

template< class ExecutionPolicy, class ForwardIt >
ForwardIt min_element( ExecutionPolicy&& policy,                    (2) (since C++17)
                       ForwardIt first, ForwardIt last );

template< class ForwardIt, class Compare >
ForwardIt min_element( ForwardIt first, ForwardIt last,             (3) (constexpr since C++17)
                       Compare comp );

template< class ExecutionPolicy, class ForwardIt, class Compare >
ForwardIt min_element( ExecutionPolicy&& policy,                    (4) (since C++17)
                       ForwardIt first, ForwardIt last,
                       Compare comp );

so what does it do? it finds the smallest element in the range [first, last). that's it. that's the function. 🎀

• 1) elements are compared using operator< (until C++20), and using std::less{} (since C++20).
• 3) elements are compared using the comparison function comp.
• 2,4) same as (1,3), but executed according to policy.

and check this — these overloads (2,4) only even participate in overload resolution 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)

iykyk 😭

---

🌸 Parameters 🌸

• first, last — forward iterators defining the range to examine. these are your "where do i start, where do i stop" besties.
• policy — the execution policy to use. see execution policy for details. 👀
• comp — a comparison function object (i.e. an object that satisfies the requirements of Compare) which returns true if the first argument is less than the second.

the signature of the comparison function should be equivalent to the following:

bool cmp(const Type1& a, const Type2& b);

okay so while the signature does not need to have const&, the function must not modify the objects passed to it, and it 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)). she's picky, she's iconic 💅

also the types Type1 and Type2 must be such that an object of type ForwardIt can be dereferenced and then implicitly converted to both of them. no cap, that part matters.

---

🦋 Type requirements 🦋

• ForwardIt must meet the requirements of LegacyForwardIterator.

---

👑 Return value 👑

iterator to the smallest element in the range [first, last). simple. 🔥

but here's the fine print: if several elements in the range are equivalent to the smallest element, it returns the iterator to the first such element. and it returns last if the range is empty. okay so it never just ghosts you with nothing — you always get an iterator back 🫶

---

⭐ Complexity ⭐

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

• 1,2) exactly max(N-1,0) comparisons using operator< (until C++20), std::less{} (since C++20).
• 3,4) exactly max(N-1,0) applications of the comparison function comp.

so it's linear, queen. it's not out here doing anything extra. max(N-1,0) and that's final. 💀

---

🌈 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.

okay real talk on that first bullet: std::terminate is not a vibe check, it's the end of your whole program. so don't be throwing out of these unless you know exactly what you're doing 🙈

---

🧚 Possible implementation 🧚

here's min_element (1), the no-frills one:

template<class ForwardIt>
ForwardIt min_element(ForwardIt first, ForwardIt last)
{
    if (first == last)
        return last;

    ForwardIt smallest = first;

    while (++first != last)
        if (*first < *smallest)
            smallest = first;

    return smallest;
}

and here's min_element (3), the one that lets you bring your own comparator:

template<class ForwardIt, class Compare>
ForwardIt min_element(ForwardIt first, ForwardIt last, Compare comp)
{
    if (first == last)
        return last;

    ForwardIt smallest = first;

    while (++first != last)
        if (comp(*first, *smallest))
            smallest = first;

    return smallest;
}

look at her go. literally so clean. 🍓

---

🎀 Example 🎀

// Run this code

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

int main()
{
    std::vector<int> v{3, 1, -4, 1, 5, 9};

    std::vector<int>::iterator result = std::min_element(v.begin(), v.end());
    std::cout << "min element has value " << *result << " and index ["
              << std::distance(v.begin(), result) << "]\n";
}

Output:

min element has value -4 and index [2]

ate. no notes. 💅✨

---

💜 Defect reports 💜

the following behavior-changing defect reports were applied retroactively to previously published C++ standards. history lesson time, bestie:

• LWG 212 — applied to C++98 — behavior as published: the return value was not specified if [first, last) is empty → correct behavior: returns last in this case.
• LWG 2150 — applied to C++98 — behavior as published: the iterator to the first non-greatest element was returned → correct behavior: corrected the return value.

the way they had to go back and fix that 😭 iconic of them to document it though.

---

🌸 See also 🌸

• max_element — returns the largest element in a range (function template)
• minmax_element — returns the smallest and the largest elements in a range (C++11) (function template)
• min — returns the smaller of the given values (function template)
• ranges::min_element — returns the smallest element in a range (C++20) (niebloid)

---

okay that's the whole page, you made it to the end, i'm so proud of you 🫶💖 this was std::min_element(3) from the C++ Standard Library manual — sourced from http://cppreference.com, dated 2024.06.10, filed under std::min_element(3). go find your smallest element, bestie. slay 🎀👑