Standard Library Function Helpers

In previous sections, when we had a function that receives another function as an argument, we've been fairly inelegant with how we specified that type.

We might just set the type to auto, but this eliminates some type safety, and doesn't document our expectations:

1class Party {
2public:
3  // This is too loose
4  bool all_of(auto Pred) {
5    return (
6      Pred(PlayerOne) &&
7      Pred(PlayerTwo) &&
8      Pred(PlayerThree)
9    );
10  }
11};

Alternatively, we've specified the exact type of argument we expect, such as a function pointer:

1class Player {
2 public:
3  bool isOnline() const { return true; }
4};
5
6class Party {
7 public:
8  using Handler = bool (*)(const Player&);  
9  bool all_of(Handler Pred) {          
10    return (
11      Pred(PlayerOne) &&
12      Pred(PlayerTwo) &&
13      Pred(PlayerThree)
14    );
15  }
16
17 private:
18  Player PlayerOne;
19  Player PlayerTwo;
20  Player PlayerThree;
21};
22
23struct OnlineChecker {
24  bool operator()(const Player& P) {
25    return P.isOnline();
26  }
27};
28
29int main() {
30  Party MyParty;
31  MyParty.all_of(OnlineChecker{});
32}

1error: 'bool Party::all_of(Party::Handler)': cannot convert argument 1 from 'OnlineChecker' to 'Party::Handler'

But this is unnecessarily restrictive. Our all_of() function doesn't care if we provide a function pointer, lambda, or functor. It will be happy to use either of them, so there's no reason to deny consumers the choice.

As of C++20, the preferred way we specify type requirements is through concepts

The standard library has already provided a concept that can help us here. The std::invocable concept is available after we include <concepts>. To specify that a function template's argument should be invocable, we would use it like this:

1#include <iostream>
2#include <concepts>
3
4void Call(std::invocable auto Callback) {
5  Callback();
6}
7
8void Greet() { std::cout << "Hello From Function\n"; }
9
10struct Greeter {
11  void operator()() {
12    std::cout << "Hello from Functor\n";
13  }
14};
15
16int main() {
17  Call(Greet);
18  Call(Greeter{});
19  Call([] { std::cout << "Hello From Lambda"; });
20}

1Hello From Function
2Hello from Functor
3Hello From Lambda

To specify the argument list of the required invocable, we would provide the types as template parameters to std::invocable. Below, we require the first argument to Call be an invocable that accepts two integer arguments:

1#include <iostream>
2#include <concepts>
3
4void Call(std::invocable<int, int> auto Func) {
5  Func(1, 2);
6}
7
8void Function(int x, int y) {
9  std::cout << "Values received by function: "
10    << x << ", " << y;
11}
12
13struct Functor {
14  void operator()(int x, int y) {
15    std::cout << "\nValues received by functor: "
16      << x << ", " << y;
17  }
18};
19
20int main() {
21  Call(Function);
22  Call(Functor{});
23  Call([](int x, int y) {
24    std::cout << "\nValues received by lambda: "
25      << x << ", " << y;
26  });
27}

Below, we update our original all_of() example to use this concept:

1#include <concepts>
2
3class Player {
4 public:
5  bool isOnline() const { return true; }
6};
7
8class Party {
9 public:
10  bool all_of(
11    std::invocable<const Player&> auto Pred) {  
12    return (
13      P(PlayerOne) &&
14      P(PlayerTwo) &&
15      P(PlayerThree)
16    );
17  }
18
19 private:
20  Player PlayerOne;
21  Player PlayerTwo;
22  Player PlayerThree;
23};
24
25struct OnlineChecker {
26  bool operator()(const Player& P) {
27    return P.isOnline();
28  }
29};
30
31int main() {
32  Party MyParty;
33  MyParty.all_of(OnlineChecker{});
34}

When our function is expected to return a bool, or something convertible to a bool, the standard library includes the std::predicate concept to help us out:

1#include <iostream>
2#include <concepts>
3
4void Call(std::predicate auto Func) {
5  std::cout << "That was a predicate";
6}
7
8void Call(auto Func) {
9  std::cout << "\nThat was not a predicate";
10}
11
12struct SomeType {};
13
14int main() {
15  Call([] { return true; });
16  Call([] { return SomeType{}; });
17}

1That was a predicate
2That was not a predicate

Similar to std::invocable, we can provide the required argument list as template parameters. Below, we create a template where an argument is required to be a predicate that accepts an int and a float:

1#include <concepts>
2#include <iostream>
3
4template <std::predicate<int, float> T>
5void LogIfTrue(T Predicate, int x, float y) {
6  if (Predicate(x, y)) {
7    std::cout << "Predicate returned true";
8  }
9}
10
11int main() {
12  LogIfTrue([](int x, float y) {
13    return x == y;
14  }, 5, 5.0f);
15}

1Predicate returned true

Our earlier all_of() function was expecting the callback to return a boolean, so we'd likely prefer to use std::predicate in this scenario, rather than the less restrictive std::invocable:

1#include <concepts>
2
3struct Player {};
4class Party {
5public:
6  template <std::predicate<Player&> T>
7  bool all_of(T Predicate){
8    return (
9      Predicate(PlayerOne) &&
10      Predicate(PlayerTwo) &&
11      Predicate(PlayerThree)
12    );
13  }
14};

The standard library currently doesn't provide a concept that requires any return type other than boolean, using std::predicate. If we need this, we can define our own. Below, we create a concept for a function that accepts two int objects and returns an int:

1#include <iostream>
2#include <concepts>
3
4template <typename T>
5concept TwoIntsToInt = requires(T Callable) {
6  { Callable(1, 1) } -> std::same_as<int>;
7};
8
9void Call(TwoIntsToInt auto Func, int x, int y) {
10  std::cout << "The callback returned: "
11    << Func(x, y);
12}
13
14int main() {
15  Call([](int x, int y) {
16    return x + y;
17  }, 1, 2);
18}

1The callback returned: 3

Below, we create a template that requires a callable return an int, and for the argument list to be provided as template parameters. This effectively replicates the behavior of std::predicate except, where std::predicate requires the function return a bool, our IntReturner concept requires an int be returned.

Note__: The ... syntax in the following example is a parameter pack__, which is how we represent a variable number of parameters. We cover this in more detail later in this chapter in our lesson on variadic functions.

1#include <iostream>
2#include <concepts>
3
4template<typename T, typename... Args>
5concept IntReturner =
6  requires(T Func, Args... args) {
7    { Func(args...) } -> std::same_as<int>;
8};
9
10template <IntReturner<int, float, double> T>
11void Call(T Func, int x, float y, double z) {
12  std::cout << "The callback returned: "
13    << Func(x, y, z);
14}
15
16int main() {
17  Call([](int x, float y, double z) -> int {
18    return x + y + z;
19  }, 1, 2.0f, 3.0);
20}

1The callback returned: 6

The std::function container within the <functional> header gives us a generalized and flexible way to represent callables such as lambdas, functors, or function pointers. If we had a callable that returns void and has no arguments, we could store it as a variable called Example using the following syntax:

1#include <functional>
2
3std::function<void()> Example;

Below, we create a container for storing a callable that receives two int arguments, and returns a bool:

1#include <functional>
2
3std::function<bool(int, int)> Example;

Class Template Argument Deduction

As with most containers, when we're providing an initial value to our std::function, we do not need to provide the template arguments. The compiler can automatically infer the type required, based on the type of object we're initializing the container with.

This technique is called class template argument deduction, or CTAD:

1#include <functional>
2
3bool Function(int x, int y) { return true; };
4
5int main() {
6  std::function Callable{Function};
7}

Why do we need std::function?

The main benefit of std::function is similar to the benefit of std::invocable - that is, it does not prescribe the specific type of callable, thereby giving us more flexibility. Below, we create a std::function that first stores a function pointer, then a functor, then a lambda:

1#include <functional>
2
3void Function(){};
4
5struct Functor{
6  void operator()(){}
7};
8
9int main() {
10  std::function Callable{Function};
11  Callable = Functor{};
12  Callable = [] {};
13}

Empty std::function containers

A std::function container can be empty. We can check for this by coercing it to a boolean:

1#include <iostream>
2#include <functional>
3
4int main() {
5  std::function<void()> Callable;
6
7  if (!Callable) {
8    std::cout << "Callable is empty";
9  }
10
11  Callable = [] {};
12
13  if (Callable) {
14    std::cout << "...but not any more!";
15  }
16}

1Callable is empty...but not any more!

We can assign nullptr to a std::function, effectively setting it to the empty state:

1#include <functional>
2#include <iostream>
3
4int main() {
5  std::function Callable{[] {}};
6
7  if (Callable) {
8    std::cout << "A function is stored";
9  }
10
11  Callable = nullptr;
12
13  if (!Callable) {
14    std::cout << "...but not any more!";
15  }
16}

1A function is stored...but not any more!

Using std::function as a member variable

The main place we'll see std::function being used is within class definitions. Below, we create a Player class that allows the outside world to provide a callback to be invoked when our Player is defeated, which it stores in a std::function.

1#include <functional>
2#include <iostream>
3
4class Player{
5 public:
6   Player(std::invocable auto DefeatCallback)
7     : OnDefeat { DefeatCallback } {}
8
9  void TakeDamage() {
10    Health -= 50;
11    if (Health <= 0 && OnDefeat) {
12      OnDefeat();
13    }
14  }
15
16 private:
17  int Health{100};
18  std::function<void()> OnDefeat;
19};
20
21int main() {
22  Player PlayerOne {[] {
23    std::cout << "The player was defeated";
24  }};
25
26  PlayerOne.TakeDamage();
27  PlayerOne.TakeDamage();
28}

1The player was defeated

When writing functional code, we'll commonly need to create very simple callables that accept two arguments and apply some basic operator on them. The standard library contains a collection of types that can help us create functors that implement these operators.

Everything we cover in this section is within the <functional> header:

1#include <functional>

Comparison Operators

A common requirement we'll have when sorting a container, for example, is to provide a function specifying how we want the container to be sorted. Typically, these functions will accept two arguments and should return true if the first argument comes before the second in our sort order.

Below, we sort a forward list in ascending order, by providing a lambda that accepts two arguments, x and y, and returns the result of x < y:

1#include <iostream>
2#include <forward_list>
3
4int main() {
5  std::forward_list Nums{3, 1, 2, 5, 4};
6
7  Nums.sort([](int x, int y) { return x < y; });
8
9  std::cout << "Sorted Container: ";
10  for (auto Num : Nums) {
11    std::cout << Num << ", ";
12  }
13}

1Sorted Container: 1, 2, 3, 4, 5,

The standard library can help us here - a functor that accepts two arguments and returns the result of using the < operator with them is available by instantiating std::less. As such, we didn't need to write the lambda - we can just do this:

1#include <forward_list>
2#include <iostream>
3#include <functional>
4
5int main() {
6  std::forward_list Nums{3, 1, 2, 5, 4};
7
8  Nums.sort(std::less{});
9
10  std::cout << "Sorted Container: ";
11  for (auto Num : Nums) {
12    std::cout << Num << ", ";
13  }
14}

1Sorted Container: 1, 2, 3, 4, 5,

A full suite of types for creating functors that accept two arguments and return the result of a comparison operator is available:

• std::less uses the < operator
• std::less_equal uses the <= operator
• std::equal_to uses the == operator
• std::not_equal_to uses the != operator
• std::greater uses the > operator
• std::greater_equal uses the >= operator

Arithmetic Operators

An algorithm like fold_left_first() accepts a collection of objects, and returns a single object. The single object is generated by folding the collection together - that is, combining two objects at a time until only one object remains.

We provide a function to specify how objects are combined. Below, we provide a lambda that adds the objects together. The net result of this is that the algorithm returns the sum of every number in our collection:

1#include <vector>
2#include <iostream>
3#include <algorithm>
4
5int main() {
6  std::vector Nums{1, 2, 3, 4, 5};
7
8  auto Sum{std::ranges::fold_left_first(
9    Nums, [](int x, int y) { return x + y; })};
10
11  std::cout << "Sum: " << Sum.value_or(0);
12}

1Sum: 15

We cover fold algorithms in more detail later in the course. For now, the key point is that the standard library provides types for creating functors that implement basic arithmetic operators like +. As such, we could replace the lambda in our previous example with an instance of std::plus:

1#include <vector>
2#include <iostream>
3#include <algorithm>
4
5int main() {
6  std::vector Nums{1, 2, 3, 4, 5};
7
8  auto Sum{std::ranges::fold_left_first(
9    Nums, std::plus{})};
10
11  std::cout << "Sum: " << Sum.value_or(0);
12}

1Sum: 15

The full collection of function objects for implementing arithmetic operations are:

• std::plus uses the binary + operator
• std::minus uses the binary - operator
• std::multiplies uses the binary * operator
• std::divides uses the / operator
• std::modulus uses the % operator

We also have std::negate, which uses the unary - operator. For example, a functor created from std::negate will accept a single argument x and will return -x.

Bitwise Operators

Less commonly, the standard library includes functors that implement the bitwise operators. We covered these operators in more detail in the previous course:

Below, we use std::bit_or to create a functor that implements the bitwise or operator |:

1#include <vector>
2#include <iostream>
3#include <algorithm>
4#include <functional>
5#include <bitset>
6
7std::bitset<3> FLAG_ONE   {1 << 0};
8std::bitset<3> FLAG_TWO   {1 << 1};
9std::bitset<3> FLAG_THREE {1 << 2};
10
11int main() {
12  std::vector Bits{FLAG_ONE, FLAG_THREE};
13
14  std::bitset Bitset{
15    std::ranges::fold_left_first(
16      Bits, std::bit_or{}
17    ).value_or(0)};
18
19  std::cout << "FLAG_ONE "
20    << (Bitset[0] ? "is" : "is not")
21    << " set\n";
22
23  std::cout << "FLAG_TWO "
24    << (Bitset[1] ? "is" : "is not")
25    << " set\n";
26
27  std::cout << "FLAG_THREE "
28    << (Bitset[2] ? "is" : "is not")
29    << " set\n";
30}

1FLAG_ONE is set
2FLAG_TWO is not set
3FLAG_THREE is set

The full collection includes:

• std::bit_or which uses the | operator
• std::bit_and which uses the binary & operator
• std::bit_xor which uses the ^ operator

We also have std::bit_not, which uses the unary ~ operator. For example, a functor created from std::bit_not will accept a single argument x and will return ~x.

In this lesson, we've explored function helpers available in the standard library. This included concepts like std::invocable and std::predicate, the std::function container, and the suite of standard library functors for implementing basic operations.

Key Takeaways

• Introduction to the std::invocable concept for specifying callable type requirements.
• Understanding the std::predicate concept for functions expected to return a boolean.
• Demonstrated how to create custom concepts for functions with specific return types beyond boolean.
• How to use std::function for storing callable objects, providing flexibility across different callable types.
• The use of class template argument deduction (CTAD) in simplifying std::function usage.
• Discussed the benefits and usage scenarios of std::function versus std::invocable and when to use each.
• Exploration of standard library function objects for implementing comparison, arithmetic, and bitwise operators, reducing the need to write our own.