Creating Custom Concepts

In the previous lesson, we introduced C++20 concepts, which allow us to determine if a type meets some specific requirements at compile time. We used concepts like std::integral and std::floating_point in our examples, but of course, we’re not restricted to just what’s available in the standard library.

We can create our own concepts to test types against the exact requirements we have for our program. In this lesson, we’ll cover the key techniques to set this up.

Writing Our Own Concepts

A basic concept looks like this:

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

We can break it down into four components:

• A template parameter list (note, this list cannot reference other concepts)
• The concept keyword
• The name we want to use for 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 we covered in the previous lesson:

1#include <concepts>
2#include <iostream>
3
4template <typename T>
5concept Integer = std::integral<T>;
6
7// As a constrained template parameter
8template <Integer T>  
9void ConstrainedTemplate(T x) {
10  std::cout << "That's an integer\n";
11}
12
13// As a compile-time boolean expression
14template <typename T>
15void UnconstrainedTemplate(T x) {
16  if constexpr (Integer<T>) {
17    std::cout << "That's an integer too\n";
18  }
19}
20
21int main() {
22  ConstrainedTemplate(1);
23  UnconstrainedTemplate(2);
24}

1That's an integer
2That's an integer too

Our Integer concept is effectively just re-implementing the std::is_integral concept under a different name, but we can of course go further.

The following Numeric 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>;

The logic that ultimately returns the boolean representing whether or not the type satisfies the concept can be arbitrarily complex.

Additionally, C++20 introduced additional syntax involving the requires keyword, which can make implementing this logic easier.

Using requires Expressions

When our requirements get more complex, trying to craft a single boolean expression to test for them can get messy. Instead, we can combine multiple requires statements within a requires expression. It looks like this:

1template <typename T>
2concept MyConcept = requires {
3  // ...
4};

Between the braces, we list all of our requirements as individual statements. For the concept to be satisfied, all of the requirements must be satisfied. Below, we use this to create a concept that is satisfied if a type is both convertible to and convertible from an int:

1#include <concepts>
2#include <iostream>
3
4template <typename T>
5concept ConvertibleToFromInt = requires {
6  requires std::convertible_to<int, T>;
7  requires std::convertible_to<T, int>;
8};
9
10template <ConvertibleToFromInt T>
11void Template(int x) {
12  std::cout << "That was convertible: "
13    << int(T{x});
14}
15
16template <typename T>
17void Template(int x) {
18  std::cout << "\nThat was not";
19}
20
21struct SomeType {
22  SomeType(int x) : Value{x} {};
23  operator int() { return Value; };
24
25  int Value;
26};
27
28int main() {
29  Template<SomeType>(42);
30  Template<std::string>(42);
31}

1That was convertible: 42
2That was not

1#include <concepts>
2#include <iostream>
3
4template <typename T>
5concept Integer = requires {
6  std::integral<T>;
7};
8
9int main() {
10  if (Integer<std::string>) {
11    std::cout << "The concept is satisfied";
12  }
13}

1The concept is satisfied

1#include <concepts>
2#include <iostream>
3
4template <typename T>
5concept Integer = requires {
6  requires std::integral<T>;
7};
8
9int main() {
10  if (!Integer<std::string>) {
11    std::cout << "The concept is not satisfied";
12  }
13}

1The concept is not satisfied

Combining and Negating requires Expressions

Our concepts can combine boolean expressions and requires statements as needed to implement more complex checks. We do this using standard boolean operators like && and ||.

Below, our concept requires the type to be a class or struct using the std::is_class type trait, and additionally requires it be convertible to and from an int using the same requires expression we created earlier:

1#include <concepts>
2#include <iostream>
3
4template <typename T>
5concept IntClass = std::is_class_v<T> &&
6  requires {
7    requires std::convertible_to<int, T>;
8    requires std::convertible_to<T, int>;
9  };
10  
SomeType Struct|Show
11struct SomeType {/*...*/};
18
19int main() {
20  if (IntClass<SomeType>) {
21    std::cout << "The concept is satisfied";
22  }
23}

1The concept is satisfied

Below, our type must be a class or struct, and convertible to either a float or an int:

1#include <concepts>
2#include <iostream>
3
4template <typename T>
5concept IntOrFloatClass = std::is_class_v<T> &&
6  requires {
7    requires std::convertible_to<int, T>;
8    requires std::convertible_to<T, int>;
9  } || requires {
10    requires std::convertible_to<float, T>;
11    requires std::convertible_to<T, float>;
12};
13
SomeType Struct|Show
14struct SomeType {/*...*/};
21
22int main() {
23  if (IntOrFloatClass<SomeType>) {
24    std::cout << "The concept is satisfied";
25  }
26}

1The concept is satisfied

We can also negate requires statements by negating the boolean they’re checking using the ! operator in the normal way. Below, we’re requiring our type be convertible from an int, but not to an int:

1template <typename T>
2concept SomeConcept = requires {
3  requires std::convertible_to<int, T>;
4  requires !std::convertible_to<T, int>;
5};

We can also negate an entire requires expression, which effectively translates to requiring at least one of the statements within the expression to be invalid.

Below, we reject a type that is simultaneously convertible from and to an int. Being convertible in one direction (or neither) is fine, but not both:

1template <typename T>
2concept SomeConcept = !requires {
3  requires std::convertible_to<int, T>;
4  requires std::convertible_to<T, int>;
5};

Functional requires Syntax

We can also use a requires expression that looks somewhat like a function:

1template <typename T>
2concept MyConcept = requires(T x) {
3  // ...
4};

Within the body of the previous expression, we can imagine x being a value of the type we’re testing - T, in this case. We then provide statements that use this value:

1template <typename T>
2concept Addable = requires(T x) {
3  x + x;
4};

It might look like we’re writing a function here, but what we’re doing is specifying requirements on the type T. In the above example, we’re asking the compiler to imagine x is an instance of our template type, T.

We’re then asking it to determine whether x + x would be a valid statement in that scenario. If this would be valid, then T satisfies our concept.

In the following example, we’re providing 4 statements, all of which must be valid for T to satisfy our Arithmetic concept:

1#include <iostream>
2
3template <typename T>
4concept Arithmetic = requires(T x) {
5  x + x;
6  x - x;
7  x * x;
8  x / x;
9};
10
11int main() {
12  if (Arithmetic<int>) {
13    std::cout << "int satisfies the concept";
14  }
15  if (!Arithmetic<std::string>) {
16    std::cout << "\nstd::string does not";
17  }
18}

1int satisfies the concept
2std::string does not

Here is a final example, where we’re again saying T must implement the + operator where the right operand is to another T.

But we have an additional requirement: whatever type is returned by that operator+ function must implement the / operator, where the right operand is an int such as 2:

1template <typename T>
2concept Averagable = requires(T x, T y){
3  (x + y) / 2;
4};

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
9int main(){
10  // This is fine
11  Average(3, 5);
12
13  // This is not
14  std::string A{"Hello"};
15  std::string B{"World"};
16  Average(A, B);
17}

Before the introduction of concepts in C++20, 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:

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

The compiler tells us that 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 also explains exactly why the concept returned false - because the std::string type does not define the / operator we specified as a requirement.

Multiple Template Parameters

Our previous concepts have using a single template parameter, but we are free to use multiple:

1#include <iostream>
2
3template <typename T1, typename T2>
4concept Addable = requires(T1 x, T2 y) {
5  x + y;
6};
7
8int main() {
9  if (Addable<int, float>) {
10    std::cout << "int is addable to float";
11  }
12  if (!Addable<int, std::string>) {
13    std::cout << "\nbut not to std::string";
14  }
15}

1int is addable to float
2but not to std::string

The order of our template parameters is important for the usual reason - it corresponds with the order of arguments.

However, when working with concepts, there is an additional consideration for our design. Specifically, the first argument will be provided automatically when the concept is used to constrain a template.

We’ve already seen examples of this. When using a concept like std::integral as a boolean expression, we need to explicitly provide the type we’re testing within the <>:

1std::integral<int>

But, when using it to constrain a template, the argument is populated automatically during substitution:

1#include <concepts>
2#include <iostream>
3
4template <std::integral T>
5void Template(T x) {
6  std::cout << "\nThat was integral too";
7}
8
9int main() {
10  // We invoke the concept with int
11  if (std::integral<int>) {
12    std::cout << "That was integral";
13  }
14  
15  // The compiler invokes the concept with int
16  Template(42);
17}

1That was integral
2That was integral too

When the concept has multiple parameters, substitution provides the value for the first parameter.

This means that if we’re using a concept to constrain template parameters, and that concept requires multiple arguments, we need to provide the additional arguments within the argument list of our template.

In the following example, our concept is called with <int, float> in both cases:

1#include <concepts>
2#include <iostream>
3
4template <typename T1, typename T2>
5concept AddableTo = requires(T1 x, T2 y) {
6  x + y;
7};
8
9template <AddableTo<float> T>  
10void Template(T x) {
11  std::cout << "that type is addable "
12    "to float too";
13}
14
15int main() {
16  if (AddableTo<int, float>) {
17    std::cout << "int is addable to float\n";
18  }
19  Template(42);
20}

1int is addable to float
2that type is addable to float too

Summary

In this lesson, we covered how to create custom concepts in C++20 to define requirements for types. The key takeaways are:

• Concepts allow us to determine if a type meets specific requirements at compile time.
• We can write our own concepts using the concept keyword and a boolean expression or a requires expression.
• The requires expression allows us to list multiple requirements that must all be satisfied for the concept to be met.
• We can combine and negate requires expressions using boolean operators like &&, ||, and !.
• Concepts can use functional requires syntax to specify requirements on how instances of a type can be used.
• Concepts can have multiple template parameters, with the first parameter being automatically provided during substitution when used to constrain a template.

Next Lesson

Using Concepts with Classes

Learn how to use concepts to express constraints on classes, ensuring they have particular members, methods, and operators.

ContinueView Course