std::ranges::max(3)

📦 version 2024.07.05, in nixpkgs unstable, opensuse-leap 16.0

💅 std::ranges::max — the C++ Standard Library glow-up you didn't know you needed

okay so bestie, you know how <algorithm> has that one friend who's just… the biggest? Yeah. That's this one. Welcome to std::ranges::max(3), a page from the C++ Standard Library (yes, published on http://cppreference.com, dated 2024.06.10, and the page itself is filed as std::ranges::max(3) — we stan an organized queen). Let's get into it 🎀

✨ NAME ✨

std::ranges::max — literally just std::ranges::max. That's the whole name. Iconic, no notes. 💅

🌸 SYNOPSIS 🌸

Defined in header <algorithm>. Here's the call signature, all three flavors, and yes, I'm giving you every character:

template< class T, class Proj = std::identity,
          std::indirect_strict_weak_order<
              std::projected<const T*, Proj>> Comp = ranges::less >

(1) (since C++20)

constexpr const T&
    max( const T& a, const T& b, Comp comp = {}, Proj proj = {} );
template< std::copyable T, class Proj = std::identity,
          std::indirect_strict_weak_order<
              std::projected<const T*, Proj>> Comp = ranges::less >

(2) (since C++20)

constexpr T
    max( std::initializer_list<T> r, Comp comp = {}, Proj proj = {} );
template< ranges::input_range R, class Proj = std::identity,
          std::indirect_strict_weak_order<
              std::projected<ranges::iterator_t<R>, Proj>> Comp = ranges::less >

(3) (since C++20)

    requires std::indirectly_copyable_storable<ranges::iterator_t<R>,
                                               ranges::range_value_t<R>*>
constexpr ranges::range_value_t<R>
    max( R&& r, Comp comp = {}, Proj proj = {} );
the way this page has three overloads and each one is serving a completely different vibe 😭

💜 What it actually does

Returns the greater of the given projected values. That's the whole plot. 🫶

  1. Returns the greater of a and b.
  2. Returns the first greatest value in the initializer list r.
  3. Returns the first greatest value in the range r.

🦋 The niebloid moment (iykyk)

The function-like entities described on this page are niebloids, which is to say — and I cannot stress enough how serious this is:

  • Explicit template argument lists cannot be specified when calling any of them.
  • None of them are visible to argument-dependent lookup.
  • When any of them are found by normal unqualified lookup as the name to the left of the function-call operator, argument-dependent lookup is inhibited.

In practice, they may be implemented as function objects, or with special compiler extensions. ✨

🍓 PARAMETERS 🍓

  • a, b — the values to compare (the contestants 👑)
  • r — the range of values to compare (the whole squad 🌈)
  • comp — comparison to apply to the projected elements
  • proj — projection to apply to the elements

⭐ RETURN VALUE ⭐

  1. The greater of a and b, according to their respective projected values. If they are equivalent, returns a. (leftmost bestie wins, no cap 💖) 2,3. The greatest value in r, according to the projection. If several values are equivalent to the greatest, returns the leftmost one. If the range is empty (as determined by ranges::distance(r)), the behavior is undefined. ⚠️ not a drill, please do not feed it an empty range

🔥 COMPLEXITY 🔥

  1. Exactly one comparison. one. single. comparison. efficient king 👑 2,3. Exactly ranges::distance(r) - 1 comparisons.

🧚 POSSIBLE IMPLEMENTATION 🧚

not me reading this and genuinely being obsessed — here's how it could look:

struct max_fn
{
    template<class T, class Proj = std::identity,
             std::indirect_strict_weak_order<
                 std::projected<const T*, Proj>> Comp = ranges::less>
    constexpr
    const T& operator()(const T& a, const T& b, Comp comp = {}, Proj proj = {}) const
    {
        return std::invoke(comp, std::invoke(proj, a), std::invoke(proj, b)) ? b : a;
    }

    template<std::copyable T, class Proj = std::identity,
             std::indirect_strict_weak_order<
                 std::projected<const T*, Proj>> Comp = ranges::less>
    constexpr
    T operator()(std::initializer_list<T> r, Comp comp = {}, Proj proj = {}) const
    {
        return *ranges::max_element(r, std::ref(comp), std::ref(proj));
    }

    template<ranges::input_range R, class Proj = std::identity,
             std::indirect_strict_weak_order<
                  std::projected<ranges::iterator_t<R>, Proj>> Comp = ranges::less>
    requires std::indirectly_copyable_storable<ranges::iterator_t<R>,
                                               ranges::range_value_t<R>*>
    constexpr
    ranges::range_value_t<R> operator()(R&& r, Comp comp = {}, Proj proj = {}) const
    {
        using V = ranges::range_value_t<R>;
        if constexpr (ranges::forward_range<R>)
            return
                static_cast<V>(*ranges::max_element(r, std::ref(comp), std::ref(proj)));
        else
        {
            auto i = ranges::begin(r);
            auto s = ranges::end(r);
            V m(*i);
            while (++i != s)
                if (std::invoke(comp, std::invoke(proj, m), std::invoke(proj, *i)))
                    m = *i;
            return m;
        }
    }
};

inline constexpr max_fn max;

🌸 NOTES 🌸

okay this is the part where I hold your hand, bestie. 🫶 Capturing the result of std::ranges::max by reference produces a dangling reference if one of the parameters is a temporary and that parameter is returned:

int n = -1;
const int& r = std::ranges::max(n + 2, n * 2); // r is dangling
🚨 do NOT do this. the vibes are rancid. the reference is dangling. I'm begging you.

💖 EXAMPLE 💖

// Run this code

#include <algorithm>
#include <iostream>
#include <string>

static_assert(std::ranges::max({0B10, 0X10, 010, 10}) == 16); // overload (2)

int main()
{
    namespace ranges = std::ranges;
    using namespace std::string_view_literals;

    std::cout << "larger of 1 and 9999: " << ranges::max(1, 9999) << '\n'
              << "larger of 'a', and 'b': '" << ranges::max('a', 'b') << "'\n"
              << "longest of \"foo\", \"bar\", and \"hello\": \""
              << ranges::max({"foo"sv, "bar"sv, "hello"sv}, {},
                             &std::string_view::size) << "\"\n";
}

Output:

larger of 1 and 9999: 9999
larger of 'a', and 'b': 'b'
longest of "foo", "bar", and "hello": "hello"

ate. no crumbs. 💀✨

🎀 SEE ALSO 🎀

  • ranges::min (C++20) (niebloid) — returns the smaller of the given values
  • ranges::minmax (C++20) (niebloid) — returns the smaller and larger of two elements
  • ranges::max_element (C++20) (niebloid) — returns the largest element in a range
  • ranges::clamp (C++20) (niebloid) — clamps a value between a pair of boundary values
  • max (function template) — returns the greater of the given values

and that's the page, bestie 💜 you're now legally obligated to know the difference between all three overloads. go forth and find the maximum. periodt.

signing off 🫶 — this was http://cppreference.com, 2024.06.10, std::ranges::max(3). drink water, avoid dangling references, mwah 💋

📦 where this page comes from