C++20 Concepts

C++20 introduced a new feature called concepts that gives us a more direct and powerful way of specifying constraints on template parameters. This feature can help prevent errors and make code more readable by limiting what types can be used with a given template. Some of the advantages include:

• Enforcing type constraints on template parameters
• Making template error messages more readable and easier to understand
• Improving code documentation by explicitly specifying what types are allowed as parameters
• Preventing unintended template instantiations by restricting what types can be used

In this lesson, we’ll introduce concepts with some examples from the standard library. We’ll then show the four main ways we can use concepts with our templates.

Finally, we’ll show how we can create our own concepts. We’ll start with some basic examples and gradually ramp up the complexity to specify more and more advanced requirements.

An Introduction to C++20 Concepts

The standard library includes a collection of pre-defined concepts we can use. They’re available from the <concepts> header:

1#include <concepts>
2

For example, the std::integral concept can tell us if a type is an integer. At their most basic usage, concepts look similar to type traits. We pass the type (and depending on the concept, possibly some additional arguments) and we get a boolean value representing whether or not the type meets the requirements of the concept.

This all happens at compile time

1#include <iostream>
2#include <concepts>
3
4int main() {
5  if constexpr (std::integral<int>) {
6    std::cout << "int is an integral";
7  }
8
9  if constexpr (!std::integral<float>) {
10    std::cout << "\nfloat isn't";
11  }
12}
13

1int is an integral
2float isn't
3

Note, concepts are also available in multiple standard library locations. Notably, this includes the <ranges> and <iterators> headers, which we’ll introduce later in this course in our chapters on containers and algorithms

There are four main ways we can use concepts within our code.

Option 1: Constrained Template Parameters

Where concepts deviate from type traits is that the language has built-in syntactic support to make them easier to use. This most notably applies when we want to use a concept to constrain the types that can be used by a template.

For example, we can replace typename with a concept to constrain a template parameter.

So, if we wanted to ensure our template type was an integer, we no longer need to manually create static assertions. Instead, we can just replace typename with a concept in our template parameter list.

So, instead of writing this:

1template <typename T>
2void SomeFunction(T x) {
3  // ...
4}
5

We can instead write this:

1template <std::integral T>
2void SomeFunction(T x) {
3  // ...
4}
5

We’re now fully documenting our type requirements, and the compiler will generate meaningful error messages if anyone tries to use our template in a way we didn’t intend:

1#include <concepts>
2
3template <std::integral T>
4T Average(T x, T y) {
5  return (x + y) / 2;
6}
7
8int main() {
9  Average(1, 2);
10  Average(1.5, 2.2); 
11}
12

1the associated constraints are not satisfied
2the concept 'std::integral<double>' evaluated to false
3

Similar to the example we showed using std::enable_if in the previous lesson, concepts allow us to route function calls to different templates, in a much clearer way:

1#include <iostream>
2#include <concepts>
3
4template <std::integral T>
5T Average(T x, T y) {
6  std::cout << "Using integral function\n";
7  return (x + y) / 2;
8}
9
10template <std::floating_point T>
11T Average(T x, T y) {
12  std::cout << "Using floating point function";
13  return (x + y) / 2;
14}
15
16int main() {
17  Average(1, 2);
18  Average(1.5, 2.2);
19}
20

1Using integral function
2Using floating point function
3

We can also use identical syntax when creating template classes:

1#include <concepts>
2
3template <std::integral T>
4class Container {
5  T Contents;
6};
7
8int main() {
9  Container<int> Stuff;
10  Container<float> MoreStuff;
11}
12

1'Container': the associated constraints are not satisfied
2the concept 'std::integral<float>' evaluated to false
3

Option 2: The requires Keyword

The addition of concepts also came with a new piece of syntax - the requires keyword. This keyword is used in a few different ways, which we’ll cover in this lesson.

Below, we use the requires keyword in a function template. It has access to the types our template is using, and will return true if the template can handle those types.

We could rewrite our previous example using requires like this:

1#include <iostream>
2#include <concepts>
3
4template <typename T>
5  requires std::integral<T>
6T Average(T x, T y) {
7  std::cout << "Using integral function\n";
8  return (x + y) / 2;
9}
10
11template <typename T>
12  requires std::floating_point<T>
13T Average(T x, T y) {
14  std::cout << "Using floating point function";
15  return (x + y) / 2;
16}
17
18int main() {
19  Average(1, 2);
20  Average(3.4, 5.3);
21}
22

1Using integral function
2Using floating point function
3

The requires method is more verbose than simply replacing typename, but it gives us some more options. For example, we can use boolean logic. In the below example, we allow our type to match one of two concepts, using a requires clause and the || operator:

1#include <concepts>
2
3template <typename T>
4  requires std::integral<T> ||
5           std::floating_point<T>
6T Average(T x, T y) {
7  return (x + y) / 2;
8}
9
10int main() {
11  Average(1, 2);
12  Average(3.4, 5.3);
13}
14

We’re also not restricted to just using concepts within requires statements - we can use other compile-time techniques too. Below, we use the std::is_base_of type trait from the previous lesson:

1#include <concepts>
2
3class Player {};
4class Monster {};
5class Goblin : public Monster {};
6
7template <typename T>
8  requires std::is_base_of_v<Player, T> ||
9           std::is_base_of_v<Monster, T>
10void Function(T Character) {}
11
12int main() {
13  Function(Goblin{});
14}
15

Note, most standard library-type traits have equivalent concepts. For example, the std::derived_from concept covers the same use cases as the std::base_of type trait, albeit the order of the two types is inverted.

We can use a requires statement with class templates in the way we might expect:

1#include <concepts>
2template <typename T>
3  requires std::integral<T>
4class Container {
5  T Contents;
6};
7

Option 3: Trailing Requires Clause

When creating function templates, we have the option of using a requires statement in a slightly different way. It can be placed between the function signature and the function body, like this:

1template <typename T>
2T Average(T x, T y)
3  requires std::integral<T>
4{
5  return (x + y) / 2;
6}
7

Option 4: Abbreviated Function Template

The final way we can use concepts is within abbreviated function templates. These allow us to create function templates by setting one or more parameter types to auto:

1auto Average(auto x, auto y) {
2  return (x + y) / 2;
3}
4

Where we want to implement concepts here, we insert the concept before the auto  type:

1auto Average(std::integral auto x,
2             std::integral auto y) {
3  return (x + y) / 2;
4}
5

Combining Concept Approaches

We are free to combine the previous techniques as we see fit. Below, we use a constrained template parameter to specify requirements for the first type, and a requires statement to restrict the second type.

For the template to be eligible for a given function call, all the requirements need to be met.

1template <std::integral TFirst, typename TSecond>
2  requires std::integral<TSecond> ||
3  std::floating_point<TSecond>
4void Function(TFirst x, TSecond y){}
5

Writing Our Own Concepts

Naturally, we’re not restricted to just using the standard library concepts. We can use concepts from any source, or write our own.

A basic concept looks like this

1#include <concepts>
2
3template <typename T>
4concept Integer = std::integral<T>;
5

We can break it down into four components:

• A template parameter list (note, this list cannot reference other concepts)
• The concept keyword
• The name of the concept
• An expression that will return true if the concept is met, or false otherwise.

We can then use our concept in any of the usual ways:

1template <Integer T>
2T Average(T x, T y) {
3  return (x + y) / 2;
4}
5

The previous concept is effectively just re-implementing the std::is_integral concept under a different name, but we can of course get more complex. The following concept combines two standard library concepts and will be satisfied if a type matches either:

1#include <concepts>
2
3template <typename T>
4concept Numeric =
5    std::integral<T> || std::floating_point<T>;
6
7template <Numeric T>
8T Average(T x, T y) {
9  return (x + y) / 2;
10}
11

More complex requirements can be specified by an alternative form of the requires syntax, which looks somewhat like a function. Within the body of this syntax, we can write code that mostly looks like normal function code:

1#include <concepts>
2
3template <typename T>
4concept Averagable =
5  requires(T x, T y) {
6    (x + y) / 2;
7  };
8

But, what we’re actually doing here is specifying requirements. In the above example, what we’re saying is for a type to satisfy our concept, it must meet two requirements.

Firstly, an object of that type must be addable to another object of that same type.

More specifically, the type T must implement an + operator, where the second operand is also a T.

Secondly, the object returned from that operation must be divisible by 2. That is, it must return a type that implements the / operator, where the second operand is an int, or convertible to an int.

If a type meets those requirements, it is Averagable, otherwise, it is not.

1#include <string>
2
3template <typename T>
4concept Averagable =
5requires(T x, T y){
6  (x + y) / 2;
7};
8
9template <Averagable T>
10T Average(T x, T y){ return (x + y) / 2; }
11
12int main(){
13  Average(3, 5);
14
15  std::string A{"Hello"};
16  std::string B{"World"};
17  Average(A, B);
18}
19

Prior to concepts, something like this would have been extremely difficult to set up, requiring advanced template metaprogramming. Now, it’s fairly straightforward, and with most compilers, the error output is much better than we’d be able to achieve previously. It may look something like this:

1main.cpp(17,3)
2'Average': no matching overloaded function found
3could be 'T Average(T,T)'
4the associated constraints are not satisfied
5the concept 'Averagable<std::string>' evaluated to false
6binary '/': 'std::string' does not define this operator
7

It’s telling us on line 17 of main.cpp, no function was found that could satisfy that specific call to Average.

It correctly identified our template function as a candidate, but ruled it out because of the type constraints we added.

It tells us exactly which constraint ruled the template out - our Averagable concept, when passed a std::string returned false

And it even tells us exactly why the concept returned false - because the std::string type does not define the / operator we specified as a requirement.

Testing Object Variables and Methods

We can write concepts that require our types to have specific methods and parameters. We just need to refer to these methods and fields within our requires block, using the normal syntax such as the . and () operators.

Below, we write a concept that checks if a type has a Render method and a hasRendered variable:

1template <typename T>
2concept Renderable =
3requires(T Object){
4  Object.Render();
5  Object.hasRendered;
6};
7
8template <Renderable T>
9void Render(T Object){ Object.Render(); }
10
11class Tree {
12public:
13  bool hasRendered;
14  void Render(){}
15};
16
17class Rock {
18public:
19  void Render(){}
20};
21
22int main(){
23  Render(Tree{});
24  Render(Rock{});
25}
26

1main.cpp(24,3): 'Render': no matching overloaded function found
2could be 'T Render(T)'
3the associated constraints are not satisfied
4the concept 'Renderable<Rock>' evaluated to false
5'hasRendered': is not a member of 'Rock'
6see declaration of 'Rock'
7

Later in this lesson, we’ll see how we can test the type of class variables, as well as the return type and parameter type of class methods.

For now, note we can also combine requires statements with other boolean expressions in our concepts. Below, we check if our type derives from the Object class, and that it has both a Render and Animate method:

1template <typename T>
2concept Animatable =
3  std::derived_from<T, Object> &&
4  requires(T Object){
5    Object.Render();
6    Object.Animate();
7  };
8

We can’t use || operators within requires blocks, but we can have multiple blocks, separated by ||. Below, we check if our type has either a Render or a Draw method:

1template <typename T>
2concept Renderable = requires(T Object){
3  Object.Render();
4} || requires(T Object){
5  Object.Draw();
6};
7

Testing Method Parameter Types

Where we wish to ensure the method accepts a type of argument, we can do that by passing arguments of the appropriate type to the method “call” within the requires block.

Below, we require that our type has a Render method and that that method accepts an int. The choice of 2 is arbitrary - we could have passed any value of the appropriate type:

1template <typename T>
2concept Renderable =
3  requires(T Object) {
4    Object.Render(2);
5  };
6

Generally, we’d want to document what this argument actually is. We can do that by adding it as a named parameter parameter to the requires block.

For example, if we expect this integer is likely to represent some a size, our concept might look something like this:

1template <typename T>
2concept Renderable =
3  requires(T Object, int Size) {
4    Object.Render(Size);
5  };
6

Falling foul of this constraint would emit an error message similar to what is shown below:

1template <typename T>
2concept Renderable =
3requires(T Object, int Size){
4  Object.Render(Size);
5};
6
7template <Renderable T>
8void Render(T Object, int Size){
9  Object.Render(Size);
10}
11
12class Tree {
13public:
14  void Render(int Size){}
15};
16
17class Rock {
18public:
19  void Render(){}
20};
21
22int main(){
23  Render(Tree{}, 42);
24  Render(Rock{}, 42); 
25}
26

1main.cpp(24,3): 'Render': no matching overloaded function found
2could be 'void Render(T,int)'
3the associated constraints are not satisfied
4the concept 'Renderable<Rock>' evaluated to false
5'Rock::Render': function does not take 1 arguments
6while trying to match the argument list '(int)'
7

In this example, we only show how we can assert a parameter type against a single specific type, such as int. Later in this lesson, we show a more advanced example where we can check if a parameter type satisfies a concept, or any other compile-time tests.

Testing Method Return Value

The syntax to test a method’s return value within a concept is a little more complex. It looks like this:

1template <typename T>
2concept Renderable = requires(T Object) {
3	{ Object.Render() } -> std::integral;
4};
5

To break this down, we wrap our method “call” in braces, { and }. We then add an arrow, ->. Finally, we provide a concept we require the return value to satisfy.

Commonly, we’ll want to assert that the return type matches a specific type, or is convertible to a specific type. The C++ specification requires us to provide a concept here rather than a type, but the standard library’s same_as and convertible_to concepts can cover our needs.

Below, we are requiring render to return an int:

1template <typename T>
2concept Renderable = requires(T Object) {
3	{ Object.Render() } -> std::same_as<int>;
4};
5

Alternatively, we can loosen our requirements, and ask it return something convertible to an int:

1template <typename T>
2concept Renderable = requires(T Object) {
3	{ Object.Render() } -> std::convertible_to<int>;
4};
5

Let's see a full example:

1#include <concepts>
2
3template <typename T>
4concept Renderable = requires(T Object){
5  { Object.Render() } -> std::same_as<int>;
6};
7
8template <Renderable T>
9void Render(T Object){ Object.Render(); }
10
11class Tree {
12public:
13  int Render(){ return 42; };
14};
15
16class Rock {
17public:
18  float Render(){ return 3.14; };
19};
20
21int main(){
22  Render(Tree{});
23  Render(Rock{});
24}
25

1main.cpp(23,3): 'Render': no matching overloaded function found
2could be 'void Render(T)'
3the associated constraints are not satisfied
4the concept 'Renderable<Rock>' evaluated to false
5the concept 'std::same_as<float,int>' evaluated to false
6'float' and 'int' are different types
7

Testing Parameter Types of Template Classes

Let's imagine we have a template class, and that class has methods that work on the templated type:

1template <typename ArgType>
2class Object {
3public:
4  void Render(ArgType Arg){}
5};
6

We have a template function that calls the Render method on incoming objects and passes an argument to that object. Both the type of the object, and the type of the argument, are template types. We’ll call the object type T, and the type to be passed to the Render function will be called ArgType:

1template <typename T, typename ArgType>
2void Render(T Object, ArgType Arg){
3  Object.Render(Arg);
4}
5
6int main(){
7  Object<int> MyObject;
8  Render(MyObject, 5);
9}
10

How can we write a concept to specify the requirements of T in this situation? We know that T requires a Render method, and that method needs to accept an argument of type ArgType. But ArgType is a template type - we don’t know what it will be.

Fortunately, as we’ve seen with some of the standard library examples, concepts are not restricted to just a single template parameter.

In this case, we can create a concept that accepts two template parameters. Our type T will be the first template parameter, and we can have a second template parameter to receive the Render method’s required argument type.

Our concept can look something like this:

1template <typename T, typename ArgType>
2concept Renderable = requires(
3  T Object, ArgType Arg
4){
5  Object.Render(Arg);
6};
7

This gives us a versatile, reusable concept that lets us check if a type has a Render method, and that that method accepts an argument. But the type of that argument is not fixed - it is something that we can change any time we want to use the concept:

1// Does Tree have a Render method that accepts an int?
2Renderable<Tree, int>
3
4// Does Rock have a Render method that accepts a std::string?
5Renderable<Rock, std::string>
6
7// Template arguments can themselves be template types
8Renderable<TemplateTypeA, TemplateTypeB>
9

The last point is crucial - the arguments passed to our concepts can be template types, so the compiler can take care of it.

This allows us to pass the types through from our template function to our concept, and the concept then reports back to tell our template if the types meet the requirements.

We can do this using a requires statement, as below:

1template <typename T, typename ArgType>
2  requires Renderable<T, ArgType>
3void Render(T Object, ArgType Arg){
4  Object.Render(Arg);
5}
6

With those changes, our code should still compile, and we’ve now specified and documented what requirements we have for our template function.

Concepts that Have Multiple Arguments

The previous example used the requires clause to invoke a concept that had multiple arguments.

1requires Renderable<T, ArgType>
2

This perhaps is the clearest way to use the concept in this case, but we could have written the previous example like this instead:

1template <typename ArgType, Renderable<ArgType> T>
2void Render(T Object, ArgType Arg){
3  Object.Render(Arg);
4}
5

It’s likely less obvious what is going on in this example, but it highlights something about concept template arguments that is important to understand.

When a concept has a single template parameter, such as std::integral, and we use it as a standalone expression, we need to provide the type we want to test as a template argument, such as std::integral<int>:

1template <typename T>
2requires std::integral<T>
3void Function(T x){}
4

However, when the concept is used to replace typename within a constrained template parameter, or prepended to auto within an abbreviated function template, the template argument is substituted into the concept for us. We don’t need to provide it - we can just use std::integral or, less commonly, std::integral<>

1template <std::integral T>
2void FunctionA(T x){}
3
4// Including <> is an option, but rarely used
5template <std::integral<> T>
6void FunctionB(T x){}
7
8// Abbreviated function template
9void FunctionC(std::integral auto x){}
10

This idea extends to concepts that have 2 (or more) template parameters in a similar way. When used in isolation, we need to provide all the parameters:

1class BaseClass {};
2
3template <typename T>
4  requires std::derived_from<T, BaseClass>
5void Function(T x){}
6

When used to replace typename or prepended to auto, the first parameter is automatically inferred, and we just need to provide the remaining parameters:

1class BaseClass {};
2
3template <std::derived_from<BaseClass> T>
4void FunctionA(T x){}
5
6void FunctionB(
7  std::derived_from<BaseClass> auto x){}
8

This has implications for how we design our own concepts. If our concept has multiple template parameters, the type that we want to inspect should be the first one. If it’s not, our concept will not be usable as a constrained template parameter or abbreviated function template.

In those contexts, the type of argument to the function becomes the first parameter of our concept - the developer using our concept cannot change that, so it makes our concept less useful.

Specifying Object Variable Types using Nested requires

We can nest additional requires expressions within other requires statements. The most common use case of this is when we want to check that a type contains a variable, and we also want to apply constraints to the type of that variable.

In the following example, our Renderable constraint is satisfied if the type has a Render method, and additionally has an isRendered field that is a boolean:

1#include <concepts>
2
3template <typename T>
4concept Renderable =
5requires(T Object){
6  Object.Render();
7  requires std::same_as<
8    decltype(Object.hasRendered),
9    bool>;
10};
11
12template <Renderable T>
13void Render(T Object){ Object.Render(); }
14
15class Tree {
16public:
17  bool hasRendered;
18  void Render(){}
19};
20
21class Rock {
22public:
23  std::string hasRendered;
24  void Render(){}
25};
26
27int main(){
28  Render(Tree{});
29  Render(Rock{});
30}
31

1main.cpp(29,3): 'Render': no matching overloaded function found
2could be 'void Render(T)'
3the associated constraints are not satisfied
4the concept 'Renderable<Rock>' evaluated to false
5the concept 'std::same_as<int,bool>' evaluated to false
6'int' and 'bool' are different types
7