Minimum and Maximum Algorithms

In this lesson, we introduce the minimum and maximum algorithms available within the C++ standard library.

All the algorithms in this section are available within the <algorithm> header:

1#include <algorithm>

We will cover clamp(), min(), min_element(), max(), max_element(), minmax(), and minmax_element().

std::ranges::clamp()

The std::ranges::clamp() function is used to ensure a value is within a specific range.

The function takes three arguments: the value to clamp, the minimum allowed value, and the maximum allowed value.

• If the value to clamp is below the minimum, clamp() returns the minimum
• If the value to clamp is above the maximum, clamp() returns the maximum
• If the value is between the minimum and maximum, clamp() returns the value

The following shows an example of clamping numbers to the 0-255 range:

1#include <algorithm>
2#include <iostream>
3
4int main() {
5  using std::ranges::clamp;
6
7  std::cout
8    << "Clamp -30: " << clamp(-30, 0, 255)
9    << "\nClamp 100: " << clamp(100, 0, 255)
10    << "\nClamp 300: " << clamp(300, 0, 255);
11}

1Clamp -30: 0
2Clamp 100: 100
3Clamp 300: 255

Return Type

The clamp() algorithm, and most other algorithms in this lesson, will return a const reference to the chosen element:

1#include <algorithm>
2#include <iostream>
3
4int main() {
5  int Value { 40 };
6
7  const int& ClampedValue {
8    std::ranges::clamp(Value, 0, 255)
9  };
10
11  std::cout << "Value:        " << &Value << '\n'
12            << "ClampedValue: " << &ClampedValue;
13}

1Value:        00000054AC2FFC14
2ClampedValue: 00000054AC2FFC14

If preferred, we can create a copy of the returned value:

1#include <algorithm>
2#include <iostream>
3
4int main() {
5  int Value { 40 };
6
7  int ClampedValue {
8    std::ranges::clamp(Value, 0, 255)
9  };
10
11  std::cout << "Value:        " << &Value << '\n'
12            << "ClampedValue: " << &ClampedValue;
13}

1Value:        000000414C36FC44
2ClampedValue: 00000040F50FF7A4

std::ranges::min()

The std::ranges::min() algorithm can return the minimum result of two expressions.

1#include <algorithm>
2#include <iostream>
3
4int main() {
5  int Result{std::ranges::min(1, 10)};  
6  std::cout << "The min value is: " << Result;
7}

1The min value is: 1

Naturally, this is only useful if we don’t know which value will be the minimum - that is, where one or more of the arguments is a more complex expression such as a function call. Instead of writing logic like this:

1int MyFunction() {
2  int A{FuncA()};
3  int B{FuncB()};
4  return A < B ? A : B;
5}

We can write this, which is simpler and more descriptive:

1int MyFunction() {
2  return std::ranges::min(FuncA(), FuncB());
3}

Finding the Minimum Value in a Range

An overload of std::ranges::min() allows us to find the minimum value in a range of candidates:

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
5int main() {
6  std::vector Numbers { 2, 3, 1, 4, 5 };
7  int Result { std::ranges::min(Numbers) };
8
9  std::cout << "Smallest number: " << Result;
10}

1Smallest number: 1

If multiple objects are tied for the minimum, the algorithm will return the first (ie, leftmost) one in the range.

Using Subranges / Iterator-Sentinel Pairs

Unlike most range-based algorithms, std::ranges::min() does not allow us to specify our range as an iterator-sentinel pair as of C++23. However, we can bypass this with minimal performance overhead by creating a view (such as a subrange) from our iterator and sentinel, and then providing that view as a single argument to std::ranges::min()

Below, we find the minimum value in a collection, excluding the first and last elements:

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
5int main() {
6  std::vector Numbers{2, 3, 5, 4, 1};
7
8  int Result{std::ranges::min(
9    std::ranges::subrange(
10      Numbers.begin() + 1, Numbers.end() - 1
11    ))};
12
13  std::cout << "Smallest number: " << Result;
14}

1Smallest number: 3

Creating Views using std::ranges::subrange

This lesson introduces std::ranges::subrange, allowing us to create non-owning ranges that view some underlying container

std::ranges::min_element()

The min_element() function works with ranges in much the same way as min(). The key difference is that, whereas min() will return a reference to the smallest object, min_element() will return an iterator pointing to it.

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
5int main() {
6  std::vector Numbers{2, 3, 1, 4, 5};
7  auto Result{std::ranges::min_element(Numbers)};  
8
9  std::cout << "The min element is at index: "
10    << std::distance(Numbers.begin(), Result);
11
12  std::cout << "\nIts value is: " << *Result;
13}

1The min element is at index: 2
2Its value is: 1

In this example, we use this to insert a 0 before our minimum element, using the emplace() method provided by our std::vector:

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
5int main() {
6  std::vector Numbers { 2, 3, 1, 4, 5 };
7  auto Result { std::ranges::min_element(Numbers) };
8
9  Numbers.emplace(Result, 0);
10
11  for (int& i : Numbers) {
12    std::cout << i << ", ";
13  }
14}

12, 3, 0, 1, 4, 5,

Using Iterator-Sentinel Pairs

The std::ranges::min_element() algorithm allows us to provide our range as an iterator-sentinel pair. Below, we use this to find the minimum element in our collection, excluding the first and last element:

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
5int main() {
6  std::vector Numbers{1, 3, 5, 4, 2};
7  auto Result{std::ranges::min_element(
8    Numbers.begin() + 1, Numbers.end() - 1)};  
9
10  std::cout << "The min element is at index: "
11    << std::distance(Numbers.begin(), Result);
12
13  std::cout << "\nIts value is: " << *Result;
14}

1The min element is at index: 1
2Its value is: 3

std::ranges::max()

Similar to std::ranges::min(), the simplest use of std::ranges::max() has us pass two values, and it returns which value is the greatest:

1#include <algorithm>
2#include <iostream>
3
4int main() {
5  int Result{std::ranges::max(1, 10)};  
6  std::cout << "The max value is: " << Result;
7}

1The max value is: 10

This is typically used to place a lower bound on some unknown value. The rectified linear unit (ReLU) function is an example of this. It receives a value and returns that same value if it is positive, or 0 otherwise. This is widely used in machine learning contexts and could be implemented using std::ranges::max() like this:

1#include <algorithm>
2#include <iostream>
3
4int ReLU(int Value) {
5  return std::ranges::max(0, Value);
6}
7
8int main() {
9  std::cout << "ReLU(-10): " << ReLU(-10);
10  std::cout << "\nReLU(10): " << ReLU(10);
11}

1ReLU(-10): 0
2ReLU(10): 10

Finding the Maximum Value in a Range

The maximum value in a range can be retrieved using the max() algorithm:

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
5int main() {
6  std::vector Numbers { 2, 3, 1, 4, 5 };
7  const int& Result { std::ranges::max(Numbers) };
8
9  std::cout << "Largest number: " << Result;
10}

1Largest number: 5

If multiple objects are tied for the maximum, the algorithm will return the first (i.e., leftmost) one in the range.

Using Subranges / Iterator-Sentinel Pairs

Similar to std::ranges::min() , the std::ranges::max() algorithm does not currently allow us to specify our range as an iterator-sentinel pair. We can circumvent this with minimum performance impact by using our desired iterator and sentinel to create an intermediate view.

Below, we find the maximum value of a collection, excluding the first and last elements:

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
5int main() {
6  std::vector Numbers{5, 3, 2, 1, 4};
7
8  int Result{std::ranges::max(
9    std::ranges::subrange(
10      Numbers.begin() + 1, Numbers.end() - 1
11    ))};
12
13  std::cout << "Largest number: " << Result;
14}

1Largest number: 3

std::ranges::max_element()

Just as min_element() returns an iterator to the smallest object in our range, the max_element() algorithm returns an iterator pointing to the largest:

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
5int main() {
6  std::vector Numbers{2, 3, 1, 4, 5};
7  auto Result{std::ranges::max_element(Numbers)};  
8
9  std::cout << "The max element is at index: "
10    << std::distance(Numbers.begin(), Result);
11
12  std::cout << "\nIts value is: " << *Result;
13}

1The max element is at index: 4
2Its value is: 5

Here, we use the iterator to insert a 0 before our maximum element:

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
5int main() {
6  std::vector Numbers { 2, 3, 1, 4, 5 };
7  auto Result { std::ranges::max_element(Numbers) };
8
9  Numbers.emplace(Result, 0);
10
11  for (int& i : Numbers) {
12    std::cout << i << ", ";
13  }
14}

12, 3, 1, 4, 0, 5,

Using Iterator-Sentinel Pairs

We can provide our range to std::ranges::max_element() as an iterator-sentinel pair if needed. Below, we use this technique to find the maximum value in a collection, excluding the first and last elements:

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
5int main() {
6  std::vector Numbers{2, 3, 1, 4, 5};
7  auto Result{std::ranges::max_element(  
8    Numbers.begin() + 1, Numbers.end() - 1)};  
9
10  std::cout << "The max element is at index: "
11    << std::distance(Numbers.begin(), Result);
12
13  std::cout << "\nIts value is: " << *Result;
14}

1The max element is at index: 3
2Its value is: 4

std::ranges::minmax()

As the name suggests, the minmax() function is a combination of the min() and max() functions. In its most basic usage, we provide two arguments, and it returns a simple struct. The smaller of the two arguments will be in the min member variable, whilst the larger will be in the max member variable:

1#include <algorithm>
2#include <iostream>
3
4int main() {
5  auto Result{std::ranges::minmax(10, 1)};  
6
7  std::cout << "Min: " << Result.min
8    << ", Max: " << Result.max;
9}

1Min: 1, Max: 10

We’d typically use structured binding with this return type:

1#include <algorithm>
2#include <iostream>
3
4int main() {
5  auto [min, max]{std::ranges::minmax(10, 1)};  
6
7  std::cout << "Min: " << min
8    << ", Max: " << max;
9}

1Min: 1, Max: 10

Structured Binding

This lesson introduces Structured Binding, a handy tool for quickly unpacking simple data structures

Using minmax() on a range

We can retrieve both the minimum and maximum values in a range at once using the minmax() algorithm. This algorithm returns a struct with two properties: min and max:

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
5int main() {
6  std::vector Numbers { 2, 3, 1, 4, 5 };
7  const auto& Result { std::ranges::minmax(Numbers) };
8
9  std::cout << "Smallest: " << Result.min;
10  std::cout << "\nLargest: " << Result.max;
11}

1Smallest: 1
2Largest: 5

If multiple objects are tied for the maximum, the max property will contain the last (ie, the rightmost) one in the range.

We’d also typically use structured binding to access the return values from this overload of minmax():

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
5int main() {
6  std::vector Numbers { 2, 3, 1, 4, 5 };
7  const auto& [min, max] {
8    std::ranges::minmax(Numbers)
9  };
10
11  std::cout << "Smallest number: " << min;
12  std::cout << "\nLargest number: " << max;
13}

1Smallest number: 1
2Largest number: 5

Using Iterator-Sentinel Pairs

Because the two-argument overload of std::ranges::minmax() is reserved for the initial use case where we provide two values, we can’t currently provide a range as an iterator-sentinel pair.

However, as with previous examples, we can easily implement this behavior when needed by introducing an intermediate view. Below, we find the minimum and maximum elements of our collection, excluding the first and last elements:

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
5int main() {
6  std::vector Numbers{1, 3, 2, 4, 5};
7
8  auto[min, max]{std::ranges::minmax(
9    std::ranges::subrange{  
10      Numbers.begin() + 1, Numbers.end() - 1}  
11  )};
12
13  std::cout << "Min: " << min
14    << ", Max: " << max;
15}

1Min: 2, Max: 4

std::ranges::minmax_element()

Finally, we have minmax_element(), which will return iterators that point to the minimum and maximum objects of our range:

1#include <algorithm>
2#include <iostream>
3#include <list>
4
5int main() {
6  std::list Numbers { 2, 3, 1, 4, 5 };
7  auto [min, max] {
8    std::ranges::minmax_element(Numbers)
9  };
10
11  std::cout << "Min element: " << *min
12    << ", Index: "
13    << std::distance(Numbers.begin(), min);
14
15  std::cout << "\nMax element: " << *max
16    << ", Index: "
17    << std::distance(Numbers.begin(), max);
18}

1Min element: 1, Index: 2
2Max element: 5, Index: 4

Similar to other _element variations of these algorithms, this is mostly used if our follow-up logic is based on where the minimum and maximum elements were found in the collection.

Below, we use the iterators returned from minmax_element() to insert a 0 before both our minimum and maximum elements:

1#include <algorithm>
2#include <iostream>
3#include <list>
4
5int main() {
6  std::list Numbers { 2, 3, 1, 4, 5 };
7  auto [min, max] {
8    std::ranges::minmax_element(Numbers)
9  };
10
11  Numbers.insert(min, 0);
12  Numbers.insert(max, 0);
13
14  for (int& i : Numbers) {
15    std::cout << i << ", ";
16  }
17}

12, 3, 0, 1, 4, 0, 5,

Using Iterator-Sentinel Pairs

As usual, we can provide our range as an iterator-sentinel pair rather than as a single argument. Below, we use this technique to find the minimum and maximum elements in our collection, excluding the first and last objects:

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
5int main() {
6  std::vector Numbers { 5, 3, 2, 4, 1 };
7  auto [min, max] {std::ranges::minmax_element(
8    Numbers.begin() + 1, Numbers.end() - 1)};
9
10  std::cout << "Min element: " << *min
11    << ", Index: "
12    << std::distance(Numbers.begin(), min);
13
14  std::cout << "\nMax element: " << *max
15    << ", Index: "
16    << std::distance(Numbers.begin(), max);
17}

1Min element: 2, Index: 2
2Max element: 4, Index: 3

Type Requirements

For types to be directly supported by minimum and maximum algorithms, they generally need to implement all six of the comparison operators: >, <, >=, <=, ==, and !=. Below, we define a compatible type:

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
5struct MyStruct {
6  int Value;
7  bool operator<(const MyStruct& Other) const {
8    return Value < Other.Value;
9  }
10  bool operator<=(const MyStruct& Other) const {
11    return Value <= Other.Value;
12  }
13  bool operator>(const MyStruct& Other) const {
14    return Value > Other.Value;
15  }
16  bool operator>=(const MyStruct& Other) const {
17    return Value >= Other.Value;
18  }
19  bool operator==(const MyStruct& Other) const {
20    return Value == Other.Value;
21  }
22  bool operator!=(const MyStruct& Other) const {
23    return Value != Other.Value;
24  }
25};
26
27int main() {
28  std::vector Numbers {
29    MyStruct { 2 },
30    MyStruct { 3 },
31    MyStruct { 1 },
32    MyStruct { 4 },
33    MyStruct { 5 }
34  };
35
36  const MyStruct& min {
37    std::ranges::min(Numbers) };
38
39  std::cout << "Smallest: " << min.Value;
40}

1Smallest: 1

C++20 Expression Rewriting

C++20’s expression rewriting feature makes it easier to implement comparison operators for our custom types. Rather than needing to define all 6 operators as we did above, we only need to define two - the == operator and the "spaceship operator" <=>

We cover expression rewriting and the spaceship operator in more detail later in the course.

The Spaceship Operator and Expression Rewriting

A guide to simplifying our comparison operators using C++20 features

If we have C++20 available and want to take advantage of expression rewriting, our previous example can be simplified to this:

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
5struct MyStruct {
6  int Value;
7  bool operator==(const MyStruct& Other) const {
8    return Value == Other.Value;
9  }
10  std::strong_ordering operator<=>(
11    const MyStruct& Other) const {
12    return Value <=> Other.Value;
13  }
14};
15
16int main() {
17  std::vector Numbers {
18    MyStruct { 2 },
19    MyStruct { 3 },
20    MyStruct { 1 },
21    MyStruct { 4 },
22    MyStruct { 5 }
23  };
24
25  const MyStruct& min {
26    std::ranges::min(Numbers) };
27
28  std::cout << "Smallest: " << min.Value;
29}

1Smallest: 1

Custom Comparison Functions

The algorithms we covered in this lesson allow us to provide a custom comparison function. This function will accept two objects of the appropriate type and should return true if the first object is "smaller" than the second.

When providing a custom comparison function, the type stored within our collection does not need to have comparison operators implemented, as the algorithm will use our comparison function instead of those operators.

In the following example, we use a custom comparison function to find out which player has the lowest health:

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
Player Class|Show
5class Player {/*...*/};
18
19int main() {
20  std::vector Party{
21    Player{"Roderick", 100},
22    Player{"Anna", 200},
23    Player{"Robert", 500}
24  };
25
26  auto Comparer {
27      [](Player& A, Player& B) {
28      return A.GetHealth() < B.GetHealth();
29    }
30  };
31
32  const Player& LowestHealth{
33    std::ranges::min(Party, Comparer)
34  };
35
36  std::cout << "Lowest Health: "
37            << LowestHealth.GetName();
38}

1Lowest Health: Roderick

Projection Functions

All the algorithms in this lesson accept an additional optional third argument, which can be a projection function. Projection is a standard feature of range-based algorithms, and we cover it in more detail here:

Projection Functions

Learn how to use projection functions to apply range-based algorithms on derived data

In the following example, we use std::abs() as a projection function for the min() algorithm, to find the number in our collection with the lowest absolute value. Because we want to use the default comparison function, we pass {} in that position:

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
5int Projector(int x) { return std::abs(x); }
6
7int main() {
8  std::vector Nums {-10, -3, 1, 4};
9
10  int Min{std::ranges::min(Nums, {}, Projector)};
11
12  std::cout << "Minimum Absolute Value: " << Min;
13}

1Minimum Absolute Value: 1

In the following example, we find the Player with the lowest health, by using a Player method as the projection function:

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
Player Class|Show
5class Player {/*...*/};
18
19int main() {
20  std::vector Party {
21    Player{"Roderick", 100},
22    Player{"Anna", 200},
23    Player{"Robert", 500}
24  };
25
26  const Player& LowestHealth{std::ranges::min(
27    Party, {}, &Player::GetHealth)};
28
29  std::cout << "Lowest Health: "
30            << LowestHealth.GetName();
31}

1Lowest Health: Roderick

Using Pre-Range Algorithms

The algorithms covered in this chapter use the <ranges> library, introduced in C++20. When targeting specifications before C++20, there are older variations of all these functions. They are available by excluding the ranges specification.

For example, instead of using std::ranges::min(), we can use std::min():

1#include <algorithm>
2#include <iostream>
3
4int main() {
5  int Result{std::min(1, 10)};  
6  std::cout << "The min value is: " << Result;
7}

1The min value is: 1

These older variations have some limitations:

• They don’t support projection
• The overloads that work on collections tend to expect the collection to be provided as a std::initializer_list, which is less convenient ranges
• The overloads that directly accept iterators require the end to be defined by an iterator, rather than the more flexible sentinel pattern

Defining Ranges using Sentinels

An alternative way of defining ranges, and why we sometimes need to use them

However, use of the older algorithms remains common, and may even be preferred for simple use cases like the previous std::min() example.

Summary

In this lesson, we explored the seven key min/max algorithms offered by the C++ standard library. The main points we learned include:

• The functionality and application of clamp(), min(), min_element(), max(), max_element(), minmax(), and minmax_element() within the <algorithm> header.
• Implementing custom comparison functions to refine how algorithms determine the 'smaller' or 'larger' elements.
• The type requirements for objects manipulated by these algorithms, with examples of how to implement these requirements using comparison operators or the C++20 spaceship operator for custom types.
• Applying projection functions to transform elements before comparison.
• The differences between the C++20 <ranges> variations of these algorithms and their earlier, non-range counterparts.

Next Lesson

Movement Algorithms

An introduction to the seven movement algorithms in the C++ standard library: move(), move_backward(), rotate(), reverse(), shuffle(), shift_left(), and shift_right().

ContinueView Course