Variadic Functions

Often, we’ll find ourselves wanting to implement a function that can accept any number of arguments. Our reasons for needing to do this broadly fall into two categories:

1. API Design / Optimising Developer Experience

Sometimes, the most intuitive API we can provide for a function is a highly flexible parameter list. For example, if we’re creating a logging library, the friendliest way to let ourselves or other developers use it is probably to just let them pass everything they want to log as arguments:

1Log(A, B, C);

But we don’t know in advance how many things a consumer is going to want to log in a single function call. We could just pick an arbitrary limit like 10 and throw an error if someone goes over that. But, as we’ll soon learn, such a restriction is not necessary.

2. Forwarding Arguments to an Unknown Function

Often, we’ll need to write a function that accepts arguments that ultimately need to be passed on to another function. And, at the time we’re writing our code, we don’t know what that function will be, or how many arguments it will accept.

We’ve seen examples of this in the standard library, such as the std::make_unique() and std::make_shared() functions to create smart pointers and the emplace() methods that exist on various containers.

These functions accept a list of arguments that will be passed along to a constructor. But they don’t know which constructor they’re forwarding to, or even the type they’re constructing. That depends on a template parameter. As such, these types of functions need to have a highly flexible parameter list.

Parameter Packs

The key mechanism that lets modern C++ functions accept a variable number of parameters is a parameter pack.

A parameter pack is a collection of zero or more parameters. There are two types:

• Template parameter packs are collections of template parameters
• Function parameter packs are collections of function parameters

We define a parameter pack using ... syntax, often called an ellipsis.

The following example shows a function template, using both a template parameter pack and a function parameter pack.

In this case, we’ve called our template parameter pack Types and our function parameter pack Arguments, but we’re free to use any name, subject to the usual naming rules.

1template <typename... Types>
2void MyFunction(Types... Arguments){
3  // ...
4}

A function that uses a parameter pack is called a variadic function, and can be called with a variable number of arguments:

1template <typename... Types>
2void MyFunction(Types... Arguments){
3  std::cout << "Hello!\n";
4}
5
6int main(){
7  MyFunction();
8  MyFunction(3);
9  MyFunction(42, false, "Hello");
10}

1Hello!
2Hello!
3Hello!

References within Parameter Packs

It’s also possible to capture arguments by reference, using the & operator in the usual way:

1template <typename... Types>
2void Function(Types&... Arguments){
3  // ...
4}

And by const references:

1template <typename... Types>
2void Function(const Types&... Arguments){
3  // ...
4}

We can also use &&, but it doesn’t necessarily denote an rvalue reference. When suffixed to a deduced type (such as a template or auto) the && syntax denotes a forwarding reference, which is sometimes also called a universal reference.

We cover this in detail later in this chapter. For now, we can note that using && with our template type allows our function to capture both lvalue and rvalue references:

1template <typename... Types>
2void Function(Types&&... Arguments){
3  // ...
4}
5
6int main(){
7  int A{1};
8  Function(A, 2);
9}

We covered lvalues and rvalues in our earlier lesson on move semantics, and we have a dedicated lesson later in the course that covers forwarding, and forwarding references.

Move Semantics

Learn how we can improve the performance of our types using move constructors, move assignment operators and std::move()

The sizeof… operator

A variation of the sizeof operator is available to return the number of parameters in a parameter pack. It is the sizeof... operator:

1template <typename... Types>
2void Function(Types... Arguments){
3  std::cout
4    << "Received "
5    << sizeof...(Arguments)
6    << " Arguments";
7}
8
9int main(){ Function(42, "Hello", true); }

1Received 3 Arguments

Unpacking Parameter Packs

Once we have a parameter pack, we will often need to "expand" or "unpack" it to its constituent parameters. Typically, this is done to get a series of values to forward to some other function, as individual arguments.

To do this, we also rely on the ellipsis syntax. In the following example, we expand our parameter pack to provide arguments to a std::tuple constructor:

1template <typename... Types>
2void MyFunction(Types... Arguments){
3  std::tuple Tuple{Arguments...};
4}

We covered tuples in more detail in an earlier lesson:

Tuples and std::tuple

A guide to tuples and the std::tuple container, allowing us to store objects of different types.

std::tuple is a template class. In the above example, we were using Class Template Argument Deduction (CTAD) to let the compiler figure out the template parameters based on our initialization values.

But we can unpack template parameters in the same way, should we ever need or want to:

1template <typename... Types>
2void MyFunction(Types... Arguments) {
3  std::tuple<Types...> Tuple { Arguments... };
4}

While expanding our parameter pack, we can use any expression that includes the name of our pack. Above, we use the most basic expression - Arguments - but we can use more elaborate expressions if needed.

Each argument of our parameter pack will be passed into that expression in turn, and we then forward the value that the expression returns.

In the following example, we calculate what each argument will be if we multiply it by 2, and we forward those values instead of our original parameter pack values.

Typically, tasks like this will require the introduction of additional brackets to control the order of operations:

1#include <iostream>
2#include <tuple>
3
4template <typename... Types>
5void Function(Types... Arguments){
6  std::tuple Tuple{(Arguments * 2)...};
7
8  std::cout << "First Object in Tuple: "
9    << std::get<0>(Tuple);
10}
11
12int main(){ Function(2, 5, 10); }

1First Object in Tuple: 4

In the following example, we pass each argument to a function and forward the return values of those function calls to our tuple constructor. This unlocks a lot of possibilities, but below, our function is simply logging the value and then returning it:

1#include <iostream>
2#include <tuple>
3
4template <typename T>
5T Log(T Object){
6  std::cout << Object << '\n';
7  return Object;
8}
9
10template <typename... Types>
11void Function(Types... Arguments){
12  std::tuple Tuple{Log(Arguments)...};
13
14  std::cout << "First Object in Tuple: "
15    << std::get<0>(Tuple);
16}
17
18int main(){ Function(2, 5, 10); }

12
25
310
4First Object in Tuple: 2

Compile Time Conditionals and SFINAE

When writing variadic functions, quite often the code we write will be invalid if the size of our argument list is 0. This is true of our previous tuple examples - if Function were ever called with 0 arguments, our code would fail to compile.

A simple if statement does not solve this, as if statements are evaluated at run time. The compiler doesn’t know what will happen at run time, so it requires all branches of our code to be syntactically valid.

As such, we’ll often be using if constexpr statement in our variadic functions. These blocks remove code entirely from our application at compile time if a condition is not met.

In the following example, we only construct the tuple if our function was called with 1 or more arguments:

1#include <iostream>
2#include <tuple>
3
4template <typename... Types>
5void Function(Types... Arguments){
6  if constexpr (sizeof...(Arguments) > 0) {
7    std::tuple Tuple{Arguments...};
8
9    std::cout << "First Argument: "
10      << std::get<0>(Tuple);
11  } else {
12    std::cout << "\nParameter pack is empty!";
13  }
14}
15
16int main(){
17  Function(42, false, "Hello");
18  Function();
19}

1First Argument: 42
2Parameter pack is empty!

In our earlier lessons on templates, we covered the substitution failure is not an error (SFINAE) concept. That applies here too - just because a template instantiation resulted in invalid code, that does not mean our entire project has an error.

It just means that that specific template can’t handle the argument list we used. Rather than immediately throwing an error, the compiler will check if other templates can generate a valid function that can handle our invocation. It only becomes an error if no templates can handle the request.

We could make another template to handle the scenario of our function being called without arguments. Or, as we’ve done above, use compile-time logic to make our existing template compatible even if our parameter pack is empty.

Ensuring Variadic Function Calls Have Arguments

Parameter packs can have any number of arguments, and as we’ve seen, that number can include 0

In most scenarios where we’re creating variadic functions, the idea that they will be called with zero arguments doesn’t make sense for our use case.

We can ensure our template function is only callable with 1 or more arguments by pulling the first parameter out of the pack, and using it like we would a regular parameter.

In the following example, we’ve separated our first parameter, both in the template parameter list (where we’ve called the type T1) and in the function parameter list (where we’ve called the argument Arg1):

1#include <iostream>
2#include <tuple>
3
4template <typename T1, typename... Types>
5void Function(T1 Arg1, Types... Arguments){
6  std::tuple Tuple{Arg1, Arguments...};
7}
8
9int main(){
10  Function(42, false, "Hello");
11  Function();
12}

Now, our function can no longer be called without at least one argument. The previous example generates a compilation error:

1'Function': no matching overloaded function found

Implementing Variadic Logic

Sometimes, our variadic functions have requirements that are a little more complex than simply forwarding their parameters to some other function.

Rather, our function needs to directly implement logic that works with any number of function parameters. Typically, the best way of accomplishing this involves using the recursive techniques we covered earlier in this chapter.

Recursion and Memoization

An introduction to recursive functions, their use cases, and how to optimize their performance

Most commonly, this means handling the first parameter in the pack, and then recursively re-calling the function with the remaining parameters.

This has the effect where every subsequent recursive call has one fewer argument than the previous. Eventually, we have a call where the sizeof... our parameter pack is 0, at which case we can stop the recursion:

1#include <iostream>
2
3template <typename T1, typename... Types>
4void Log(T1 First, Types... Others) {
5  std::cout << "Logging: " << First << '\n';
6  if constexpr (sizeof...(Others) == 0) {  
7    // Base Case - Stop Recursion
8    std::cout << "Done!";
9  } else {
10    // Recursive Case
11    std::cout << sizeof...(Others)
12      << " Parameter(s) Remaining\n\n";
13    Log(Others...);
14  }
15}
16
17int main() {
18  Log(42, 9.8, "Hello");
19}

1Logging: 42
22 Parameter(s) Remaining
3
4Logging: 9.8
51 Parameter(s) Remaining
6
7Logging: Hello
8Done!

The combination of parameter packs and recursion can be quite difficult to understand, so don’t worry if the flow of the previous program is difficult to follow. If it doesn’t make sense, it may be helpful to step through it in a debugger. Alternatively, the following program implements the same idea, but in a slightly different way:

1#include <iostream>
2
3template <typename T1, typename... Types>
4void Log(T1 First, Types... Others){
5  std::cout << "Logging: " << First << '\n';
6  if constexpr (sizeof...(Others) > 0) {
7    std::cout << sizeof...(Others)
8      << " Parameter(s) Remaining\n\n";
9    Log(Others...);
10  }
11}
12
13int main(){
14  Log(42, 9.8, "Hello");
15}

1Logging: 42
22 Parameter(s) Remaining
3
4Logging: 9.8
51 Parameter(s) Remaining
6
7Logging: Hello

Another variation of this recursive behavior is shown below. In this example, once the size of our argument list reaches 1, our call to Log is handled by a different, non-recursive function:

1#include <iostream>
2
3template <typename T>
4void Log(T Object){
5  std::cout << "Logging: " << Object;
6}
7
8template <typename T1, typename... Types>
9void Log(T1 First, Types... Others){
10  std::cout << "Logging: " << First << '\n';
11  Log(Others...);
12}
13
14int main(){
15  Log(42, 9.8, "Hello");
16}

1Logging: 42
2Logging: 9.8
3Logging: Hello

Using these template-based recursion techniques can result in the compiler generating a lot of functions. This is particularly true if we’re using our variadic templates heavily throughout our project, with a wide variety of argument types.

The raw volume of code involved in a project can have performance implications in many environments. If we can solve our specific problem without using variadic functions at all, it’s often worth avoiding them.

When we do need to use variadic functions, C++17 introduced fold expressions, which can help us mitigate some of the problems. These provide us with more succinct options to implement simple recursive behaviors that cover most use cases, without the overhead of full-fledged recursion.

We can get very close to our previous behavior with a one-line fold expression:

1#include <iostream>
2
3template <typename... Types>
4void Fold(Types... Args){
5  (std::cout << ... << Args);
6}
7
8int main(){
9  Fold("Hello ", "World", '!');
10}

1Hello World!

We explain how this works, and cover fold expressions in detail, in our next lesson.

Summary

In this lesson, we covered variadic functions, learning how they enable functions to accept any number of arguments through parameter packs. The key topics we learned include:

• Variadic functions allow for a variable number of arguments, which is useful for API design and argument forwarding.
• Parameter packs can be divided into template parameter packs and function parameter packs, both defined using the ellipsis syntax.
• Arguments within parameter packs can be captured by value, by reference, by const reference, and as forwarding references to support both lvalue and rvalue references.
• The sizeof... operator helps determine the number of arguments in a parameter pack, useful for conditional logic and compile-time evaluations.
• Unpacking parameter packs enables forwarding arguments to other functions or constructors, such as when initializing a std::tuple.
• Compile-time conditionals with if constexpr and techniques like SFINAE ensure code validity even when argument lists vary in size, including zero arguments.
• Ensuring variadic function calls have at least one argument can be achieved by separating the first parameter from the rest of the pack.
• Implementing variadic logic often involves recursive template function calls, where each call handles a subset of the parameter pack until all arguments are processed.
• Fold expressions introduced in C++17 offer a concise and efficient way to apply an operation to each element in a parameter pack

Next Lesson

Fold Expression

An introduction to C++17 fold expressions, which allow us to work more efficiently with parameter packs

ContinueView Course