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>
2

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

Lets get started with clamp

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}
12

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

The clamp algorithm, and every other algorithm 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  Value = 50;
12
13  std::cout << ClampedValue;
14}
15

150
2

std::ranges::min

The minimum value in a range can be retrieved using min:

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

1Smallest number: 1
2

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

std::ranges::min_element

The min_element function works 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.

In this example, we use this to insert a 0 before our minimum element:

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
5int main() {
6  std::vector<int> 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}
15

12 3 0 1 4 5
2

std::ranges::max

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 << "Smallest number: " << Result;
10}
11

1Largest number: 5
2

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

std::ranges::max_element

Similar to min and min_element, we can instead access an iterator that points to our maximum element. 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}
15

12 3 1 4 0 5
2

std::ranges::minmax

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. We can use it like this:

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}
12

1Smallest: 1
2Largest: 5
3

Typically, we’d use structured binding when retrieving the results from 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}
14

1Smallest number: 1
2Largest number: 5
3

C++ Structured Binding

Learn some syntax added to C++ recently, which makes dealing with our structs a little cleaner

If multiple objects are tied for the minimum, the min property will contain the first (ie, the leftmost) one in the range

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

std::ranges::minmax_element

Finally, we have minmax_element, which will return iterators that point to the minimum and maximum objects of our range. Here, we use the iterators 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}
18

12 3 0 1 4 0 5
2

Minimum and Maximum Algorithms with Custom Types

For our custom types to be directly supported by minimum and maximum algorithms, they generally need to implement all six of the comparison operators: >, <, >=, <=, ==, and !=

Here is an example:

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 { std::ranges::min(Numbers) };
37
38  std::cout << "Smallest number: " << min.Value;
39}
40

1Smallest number: 1
2

Minimum and Maximum Algorithms with Custom Comparison Functions

An optional second argument to our min and max algorithms (aside from clamp) allows us to specify a 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.

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

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
5class Character {
6 public:
7  Character(std::string Name, int Health)
8      : Name(std::move(Name)), Health(Health){};
9
10  std::string GetName() const { return Name; }
11  int GetHealth() const { return Health; }
12
13 private:
14  std::string Name;
15  int Health;
16};
17
18int main() {
19  std::vector Party{
20    Character{"Legolas", 100},
21    Character{"Gandalf", 200},
22    Character{"Gimli", 500}
23  };
24
25  auto Comparer {
26    [](Character& A, Character& B) {
27      return A.GetHealth() < B.GetHealth();
28    }
29  };
30
31  const Character& LowestHealth {
32    std::ranges::min(Party, Comparer)
33  };
34
35  std::cout << "Lowest Health: "
36            << LowestHealth.GetName();
37}
38

1Lowest Health: Legolas
2

Minimum and Maximum Algorithms with Projection

All the algorithms in this lesson (aside from clamp) accept an additional optional third argument, which can be a projection function. We cover projection in detail here:

Projections and Algorithms

Learn how to use projections with standard library algorithms in C++

In this example, we find the Character with the lowest health, by passing a projection function to the min algorithm:

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
5class Character {
6 public:
7  Character(std::string Name, int Health)
8      : Name(std::move(Name)), Health(Health){};
9
10  std::string GetName() const { return Name; }
11  int GetHealth() const { return Health; }
12
13 private:
14  std::string Name;
15  int Health;
16};
17
18int main() {
19  std::vector Party {
20    Character { "Legolas", 100 },
21    Character { "Gandalf", 200 },
22    Character { "Gimli", 500 }
23  };
24
25  const Character& LowestHealth {
26    std::ranges::min(Party, {}, &Character::GetHealth)
27  };
28
29  std::cout << "Lowest Health: "
30            << LowestHealth.GetName();
31}
32

1Lowest Health: Legolas
2