Projection Functions

When we’re using an algorithm that acts on items in a collection, often we don’t want the exact values in the collection to be the input.

For example, we might have a collection of numbers, and we want to sort them by their absolute value.

Or, we have a collection of Player objects, and we want to run an algorithm on a property of those objects, such as their email addresses.

Projection Functions

To generalize the above ideas, we want a way for our algorithms to receive projections of the objects in our collection. Each projection is based on the original object but can have a different value, and even a different type.

To support this, almost every range-based algorithm in the <ranges> library has an overload that receives a projection function.

These functions will receive objects within our collection as a parameter and will return a new object based on that parameter.

The algorithm will then use these projections to drive the behavior of the algorithm.

Example: Sorting Numbers By Absolute Value

In the previous lesson, we introduced the std::ranges::sort() algorithm. Its first argument is the range we want to sort, and the optional second argument is the comparison we want to use to sort the range.

In this example, we pass {} as the comparison function, causing the algorithm to use the default value:

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
5int main() {
6  std::vector Nums{-3, 5, 0};
7  std::ranges::sort(Nums, {});
8  for (auto Num : Nums) {
9    std::cout << Num << ", ";
10  }
11}

1-3, 0, 5,

The std::ranges::sort() function also has an optional third parameter, which is how we provide a projection function.

In the next example, we pass a function that projects the numbers in our collection to their absolute value, using std::abs():

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
5int Project(int x) {
6  return std::abs(x);
7}
8
9int main() {
10  std::vector Nums{-3, 5, 0};
11  std::ranges::sort(Nums, {}, Project);
12  for (auto Num : Nums) {
13    std::cout << Num << ", ";
14  }
15}

Now, our std::ranges::sort() call has sorted our numbers by their projection - that is, their absolute value:

10, -3, 5,

1#include <algorithm>
2#include <iostream>
3#include <vector>
4
5int main() {
6  std::vector Nums{-3, 5, 0};
7
8  std::ranges::sort(Nums, [](int a, int b){
9    return std::abs(a) < std::abs(b);
10  });
11
12  for (auto Num : Nums) {
13    std::cout << Num << ", ";
14  }
15}

10, -3, 5,

Example: Projection to a Different Type

Our projection function does not need to return the same type of object that was contained in our original collection.

In this example, we sort Player objects by level, using a projection function:

1#include <vector>
2#include <iostream>
3#include <algorithm>
4
5struct Player {
6  std::string Name;
7  int Level;
8};
9
10int main() {
11  std::vector Party {
12    Player {"Legolas", 49},
13    Player {"Gimli", 47},
14    Player {"Gandalf", 53}
15  };
16
17  std::ranges::sort(Party, {}, [](Player& P) {
18    return P.Level;
19  });
20
21  for (const auto& P : Party) {
22    std::cout << "[" << P.Level << "] "
23              << P.Name << "\n";
24  }
25}

1[47] Gimli
2[49] Legolas
3[53] Gandalf

Here, we combine both a projection and a comparison function. The projection function will return an int, and then the comparison function will compare those int values:

1#include <vector>
2#include <iostream>
3#include <algorithm>
4
Unchanged Code|Show
5struct Player {/*...*/}
10
11int main() {
Unchanged Code|Show
12  std::vector Party {/*...*/}
18
19  std::ranges::sort(
20    Party,
21    [](int a, int b) { return a > b; },
22    [](Player& P) { return P.Level; }
23  );
24
Unchanged Code|Show
25  for (const auto& P : Party) {/*...*/}
30}

1[53] Gandalf
2[49] Legolas
3[47] Gimli

Example: Projection to a Class Member

Finally, we’ll often want our algorithms to receive a class member as their projection.

Where that is the case, we can simply pass a reference to that function. Below, we provide Player::GetName as our projection function, causing our Player objects to be sorted alphabetically by name:

1#include <vector>
2#include <iostream>
3#include <algorithm>
4
Player Class|Show
5class Player {/*...*/}
14
15int main() {
16  std::vector Party {
17    Player{"Legolas"},
18    Player{"Gimli"},
19    Player{"Gandalf"}
20  };
21
22  std::ranges::sort(Party, {}, &Player::GetName);
23
24  for (const auto& P : Party) {
25    std::cout << P.GetName() << '\n';
26  }
27}

1[53] Gandalf
2[47] Gimli
3[49] Legolas

Summary

In this lesson, we've explored how to utilize projection functions with C++'s <ranges> library to manipulate and sort collections based on both their inherent and derived properties. These techniques allow for more flexible and powerful data manipulation, enhancing the versatility of range-based algorithms.

Main Points Covered

• Projection functions allow algorithms to operate on transformed or derived values from the objects in a collection.
• The <ranges> library supports projection in almost all range-based algorithms, enabling operations on both value and type-transformed projections.
• Examples demonstrated sorting numbers by their absolute value and sorting objects based on a member's value, showcasing the utility of projections.
• We compared the use of projection functions with custom comparison functions, highlighting projections' broader applicability across different algorithms.
• The lesson highlighted the syntax and usage of projection functions, including how to apply them to sort collections by a property or even by a member function's return value.

Next Lesson

Standard Library Views

Learn how to create and use views in C++ using examples from std::views

ContinueView Course