9
FUNCTIONS

Functions should do one thing. They should do it well. They should do it only.
—Robert C. Martin, Clean Code

This chapter rounds out the ongoing discussion of functions, which encapsulate code into reusable components. Now that you’re armed with a strong background in C++ fundamentals, this chapter first revisits functions with a far more in-depth treatment of modifiers, specifiers, and return types, which appear in function declarations and specialize the behavior of your functions.

Then you’ll learn about overload resolution and accepting variable numbers of arguments before exploring function pointers, type aliases, function objects, and the venerable lambda expression. The chapter closes with an introduction to the std::function before revisiting the main function and accepting command line arguments.

Function Declarations

Function declarations have the following familiar form:

prefix-modifiers return-type func-name(arguments) suffix-modifiers;

You can provide a number of optional modifiers (or specifiers) to functions. Modifiers alter a function’s behavior in some way. Some modifiers appear at the beginning in the function’s declaration or definition (prefix modifiers), whereas others appear at the end (suffix modifiers). The prefix modifiers appear before the return type. The suffix modifiers appear after the argument list.

There isn’t a clear language reason why certain modifiers appear as prefixes or suffixes: because C++ has a long history, these features evolved incrementally.

Prefix Modifiers

At this point, you already know several prefix modifiers:

• The prefix static indicates that a function that isn’t a member of a class has internal linkage, meaning the function won’t be used outside of this translation unit. Unfortunately, this keyword does double duty: if it modifies a method (that is, a function inside a class), it indicates that the function isn’t associated with an instantiation of the class but rather with the class itself (see Chapter 4).
• The modifier virtual indicates that a method can be overridden by a child class. The override modifier indicates to the compiler that a child class intends to override a parent’s virtual function (see Chapter 5).
• The modifier constexpr indicates that the function should be evaluated at compile time if possible (see Chapter 7).
• The modifier [[noreturn]] indicates that this function won’t return (see Chapter 8). Recall that this attribute helps the compiler to optimize your code.

Another prefix modifier is inline, which plays a role in guiding the compiler when optimizing code.

On most platforms, a function call compiles into a series of instructions, such as the following:

1. Place arguments into registers and on the call stack.
2. Push a return address onto the call stack.
3. Jump to the called function.
4. After the function completes, jump to the return address.
5. Clean up the call stack.

These steps typically execute very quickly, and the payoff in reduced binary size can be substantial if you use a function in many places.

Inlining a function means copying and pasting the contents of the function directly into the execution path, eliminating the need for the five steps outlined. This means that as the processor executes your code, it will immediately execute your function’s code rather than executing the (modest) ceremony required for function invocation. If you prefer this marginal increase in speed over the commensurate cost in increased binary size, you can use the inline keyword to indicate this to the compiler. The inline keyword hints to the compiler’s optimizer to put a function directly inline rather than perform a function call.

Adding inline to a function doesn’t change its behavior; it’s purely an expression of preference to the compiler. You must ensure that if you define a function inline, you do so in all translation units. Also note that modern compilers will typically inline functions where it makes sense—especially if a function isn’t used outside of a single translation unit.

Suffix Modifiers

At this point in the book, you already know two suffix modifiers:

• The modifier noexcept indicates that the function will never throw an exception. It enables certain optimizations (see Chapter 4).
• The modifier const indicates that the method won’t modify an instance of its class, allowing const references types to invoke the method (see Chapter 4).

This section explores three more suffix modifiers: final, override, and volatile.

final and override

The final modifier indicates that a method cannot be overridden by a child class. It’s effectively the opposite of virtual. Listing 9-1 attempts to override a final method and yields a compiler error.

#include <cstdio>

struct BostonCorbett {
  virtual void shoot() final➊ {
    printf("What a God we have...God avenged Abraham Lincoln");
  }
};

struct BostonCorbettJunior : BostonCorbett {
  void shoot() override➋ { } // Bang! shoot is final.
};

int main() {
  BostonCorbettJunior junior;
}

Listing 9-1: A class attempting to override a final method (This code doesn’t compile.)

This listing marks the shoot method final ➊. Within BostonCorbettJunior, which inherits from BostonCorbett, you attempt to override the shoot method ➋. This causes a compiler error.

You can also apply the final keyword to an entire class, disallowing that class from becoming a parent entirely, as demonstrated in Listing 9-2.

#include <cstdio>

struct BostonCorbett final ➊ {
  void shoot()  {
    printf("What a God we have...God avenged Abraham Lincoln");
  }
};

struct BostonCorbettJunior : BostonCorbett ➋ { }; // Bang!

int main() {
  BostonCorbettJunior junior;
}

Listing 9-2: A program with a class attempting to inherit from a final class. (This code doesn’t compile.)

The BostonCorbett class is marked as final ➊, and this causes a compiler error when you attempt to inherit from it in BostonCorbettJunior ➋.

Whenever you’re using interface inheritance, you should mark implementing classes final because the modifier can encourage the compiler to perform an optimization called devirtualization. When virtual calls are devirtualized, the compiler eliminates the runtime overhead associated with a virtual call.

volatile

Recall from Chapter 7 that a volatile object’s value can change at any time, so the compiler must treat all accesses to volatile objects as visible side effects for optimization purposes. The volatile keyword indicates that a method can be invoked on volatile objects. This is analogous to how const methods can be applied to const objects. Together, these two keywords define a method’s const/volatile qualification (or sometimes cv qualification), as demonstrated in Listing 9-3.

#include <cstdio>

struct Distillate {
  int apply() volatile ➊ {
    return ++applications;
  }
private:
  int applications{};
};

int main() {
  volatile ➋ Distillate ethanol;
  printf("%d Tequila
", ethanol.apply()➌);
  printf("%d Tequila
", ethanol.apply());
  printf("%d Tequila
", ethanol.apply());
  printf("Floor!");
}
--------------------------------------------------------------------------
1 Tequila ➌
2 Tequila
3 Tequila
Floor!

Listing 9-3: Illustrating the use of a volatile method

In this listing, you declare the apply method on the Distillate class volatile ➊. You also create a volatile Distillate called ethanol within main ➋. Because the apply method is volatile, you can still invoke it ➌ (even though ethanol is volatile).

Had you not marked apply volatile ➊, the compiler would emit an error when you attempted to invoke it ➌. Just like you cannot invoke a non-const method on a const object, you cannot invoke a non-volatile method on a volatile object. Consider what would happen if you could perform such an operation: a non-volatile method is a candidate for all kinds of compiler optimizations for the reasons outlined in Chapter 7: many kinds of memory accesses can be optimized away without changing the observable side effects of your program.

How should the compiler treat a contradiction arising from you using a volatile object—which requires that all its memory accesses are treated as observable side effects—to invoke a non-volatile method? The compiler’s answer is that it calls this contradiction an error.

auto Return Types

There are two ways to declare the return value of a function:

• (Primary) Lead a function declaration with its return type, as you’ve been doing all along.
• (Secondary) Have the compiler deduce the correct return type by using auto.

As with auto type deduction, the compiler deduces the return type, fixing the runtime type.

This feature should be used judiciously. Because function definitions are documentation, it’s best to provide concrete return types when available.

auto and Function Templates

The primary use case for auto type deduction is with function templates, where a return type can depend (in potentially complicated ways) on the template parameters. Its usage is as follows:

auto my-function(arg1-type arg1, arg2-type arg2, ...) {
  // return any type and the
  // compiler will deduce what auto means
}

It’s possible to extend the auto-return-type deduction syntax to provide the return type as a suffix with the arrow operator ->. This way, you can append an expression that evaluates to the function’s return type. Its usage is as follows:

auto my-function(arg1-type arg1, arg2-type arg2, ...) -> type-expression {
  // return an object with type matching
  // the type-expression above
}

Usually, you wouldn’t use this pedantic form, but in certain situations it’s helpful. For example, this form of auto type deduction is commonly paired with a decltype type expression. A decltype type expression yields another expression’s resultant type. Its usage is as follows:

decltype(expression)

This expression resolves to the resulting type of the expression. For example, the following decltype expression yields int, because the integer literal 100 has that type:

decltype(100)

Outside of generic programming with templates, decltype is rare.

You can combine auto-return-type deduction and decltype to document the return types of function templates. Consider the add function in Listing 9-4, which defines a function template add that adds two arguments together.

#include <cstdio>

template <typename X, typename Y>
auto add(X x, Y y) -> decltype(x + y) { ➊
  return x + y;
}
int main() {
  auto my_double = add(100., -10);
  printf("decltype(double + int) = double; %f
", my_double); ➋

  auto my_uint = add(100U, -20);
  printf("decltype(uint + int) = uint; %u
", my_uint); ➌

  auto my_ulonglong = add(char{ 100 }, 54'999'900ull);
  printf("decltype(char + ulonglong) = ulonglong; %llu
", my_ulonglong); ➍
}
--------------------------------------------------------------------------
decltype(double + int) = double; 90.000000 ➋
decltype(uint + int) = uint; 80 ➌
decltype(char + ulonglong) = ulonglong; 55000000 ➍

Listing 9-4: Using decltype and auto-return-type deduction

The add function employs auto type deduction with the decltype type expression ➊. Each time you instantiate a template with two types X and Y, the compiler evaluates decltype(X + Y) and fixes the return type of add. Within main, you provide three instantiations. First, you add a double and an int ➋. The compiler determines that decltype(double{ 100. } + int{ -10 }) is a double, which fixes the return type of this add instantiation. This, in turn, sets the type of my_double to double ➋. You have two other instantiations: one for an unsigned int and int (which results in an unsigned int ➌) and another for a char and an unsigned long long (which results in an unsigned long long ➍).

Overload Resolution

Overload resolution is the process that the compiler executes when matching a function invocation with its proper implementation.

Recall from Chapter 4 that function overloads allow you to specify functions with the same name but different types and possibly different arguments. The compiler selects among these function overloads by comparing the argument types within the function invocation with the types within each overload declaration. The compiler will choose the best among the possible options, and if it cannot select a best option, it will generate a compiler error.

Roughly, the matching process proceeds as follows:

1. The compiler will look for an exact type match.
2. The compiler will try using integral and floating-point promotions to get a suitable overload (for example, int to long or float to double).
3. The compiler will try to match using standard conversions like integral type to floating-point or casting a pointer-to-child into a pointer-to-parent.
4. The compiler will look for a user-defined conversion.
5. The compiler will look for a variadic function.

Variadic Functions

Variadic functions take a variable number of arguments. Typically, you specify the exact number of arguments a function takes by enumerating all of its parameters explicitly. With a variadic function, you can take any number of arguments. The variadic function printf is a canonical example: you provide a format specifier and an arbitrary number of parameters. Because printf is a variadic function, it accepts any number of parameters.

You declare variadic functions by placing ... as the final parameter in the function’s argument list. When a variadic function is invoked, the compiler matches arguments against declared arguments. Any leftovers pack into the variadic arguments represented by the ... argument.

You cannot extract elements from the variadic arguments directly. Instead, you access individual arguments using the utility functions in the <cstdarg> header.

Table 9-1 lists these utility functions.

Table 9-1: Utility Functions in the <cstdarg> Header

The utility functions’ usage is a little convoluted and best presented in a cohesive example. Consider the variadic sum function in Listing 9-5, which contains a variadic argument.

#include <cstdio>
#include <cstdint>
#include <cstdarg>

int sum(size_t n, ...➊) {
  va_list args; ➋
  va_start(args, n); ➌
  int result{};
  while (n--) {
    auto next_element = va_arg(args, int); ➍
      result += next_element;
  }
  va_end(args); ➎
  return result;
}

int main() {
  printf("The answer is %d.", sum(6, 2, 4, 6, 8, 10, 12)); ➏
}
--------------------------------------------------------------------------
The answer is 42. ➏

Listing 9-5: A sum function with a variadic argument list

You declare sum as a variadic function ➊. All variadic functions must declare a va_list. You’ve named it args ➋. A va_list requires initialization with va_start ➌, which takes two arguments. The first argument is a va_list, and the second is the size of the variadic arguments. You iterate over each element in the variadic arguments using the va_args function. The first argument is the va_list argument, and the second is the argument type ➍. Once you’ve completed iterating, you call va_list with the va_list structure ➎.

You invoke sum with seven arguments: the first is the number of variadic arguments (six) followed by six numbers (2, 4, 6, 8, 10, 12) ➏.

Variadic functions are a holdover from C. Generally, variadic functions are unsafe and a common source of security vulnerabilities.

There are at least two major problems with variadic functions:

• Variadic arguments are not type-safe. (Notice that the second argument of va_args is a type.)
• The number of elements in the variadic arguments must be tracked separately.

The compiler cannot help you with either of these issues.

Fortunately, variadic templates provide a safer and more performant way to implement variadic functions.

Variadic Templates

The variadic template enables you to create function templates that accept variadic, same-typed arguments. They enable you to employ the considerable power of the template engine. To declare a variadic template, you add a special template parameter called a template parameter pack. Listing 9-6 demonstrates its usage.

template <typename...➊ Args>
return-type func-name(Args...➋ args) {
  // Use parameter pack semantics
  // within function body
}

Listing 9-6: A template function with a parameter pack

The template parameter pack is part of the template parameter list ➊. When you use Args within the function template ➋, it’s called a function parameter pack. Some special operators are available for use with parameter packs:

• You can use sizeof...(args) to obtain the parameter pack’s size.
• You can invoke a function (for example, other_function) with the special syntax other_function(args...). This expands the parameter pack args and allows you to perform further processing on the arguments contained in the parameter pack.

Programming with Parameter Packs

Unfortunately, it’s not possible to index into a parameter pack directly. You must invoke the function template from within itself—a process called compile-time recursion—to recursively iterate over the elements in a parameter pack.

Listing 9-7 demonstrates the pattern.

template <typename T, typename...Args>
void my_func(T x➊, Args...args) {
  // Use x, then recurse:
  my_func(args...); ➋
}

Listing 9-7: A template function illustrating compile-time recursion with parameter packs. Unlike other usage listings, the ellipses contained in this listing are literal.

The key is to add a regular template parameter before the parameter pack ➊. Each time you invoke my_func, x absorbs the first argument. The remainder packs into args. To invoke, you use the args... construct to expand the parameter pack ➋.

The recursion needs a stopping criteria, so you add a function template specialization without the parameter:

template <typename T>
void my_func(T x) {
  // Use x, but DON'T recurse
}

Revisiting the sum Function

Consider the (much improved) sum function implemented as a variadic template in Listing 9-8.

#include <cstdio>

template <typename T>
constexpr➊ T sum(T x) { ➋
    return x;
}

template <typename T, typename... Args>
constexpr➌ T sum(T x, Args... args) { ➍
    return x + sum(args...➎);
}

int main() {
  printf("The answer is %d.", sum(2, 4, 6, 8, 10, 12)); ➏
}
--------------------------------------------------------------------------
The answer is 42. ➏

Listing 9-8: A refactor of Listing 9-5 using a template parameter pack instead of va_args

The first function ➋ is the overload that handles the stopping condition; if the function has only a single argument, you simply return the argument x, because the sum of a single element is just the element. The variadic template ➍ follows the recursion pattern outlined in Listing 9-7. It peels a single argument x off the parameter pack args and then returns x plus the result of the recursive call to sum with the expanded parameter pack ➎. Because all of this generic programming can be computed at compile time, you mark these functions constexpr ➊➌. This compile-time computation is a major advantage over Listing 9-5, which has identical output but computes the result at runtime ➏. (Why pay runtime costs when you don’t have to?)

When you just want to apply a single binary operator (like plus or minus) over a range of values (like Listing 9-5), you can use a fold expression instead of recursion.

Fold Expressions

A fold expression computes the result of using a binary operator over all the arguments of a parameter pack. Fold expressions are distinct from but related to variadic templates. Their usage is as follows:

(... binary-operator parameter-pack)

For example, you could employ the following fold expression to sum over all elements in a parameter pack called pack:

(... + args)

Listing 9-9 refactors 9-8 to use a fold expression instead of recursion.

#include <cstdio>

template <typename... T>
constexpr auto sum(T... args) {
  return (... + args); ➊
}
int main() {
  printf("The answer is %d.", sum(2, 4, 6, 8, 10, 12)); ➋
}
--------------------------------------------------------------------------
The answer is 42. ➋

Listing 9-9: A refactor of Listing 9-8 using a fold expression

You simplify the sum function by using a fold expression instead of the recursion approach ➊. The end result is identical ➋.

Function Pointers

Functional programming is a programming paradigm that emphasizes function evaluation and immutable data. One of the major concepts in functional programming is to pass a function as a parameter to another function.

One way you can achieve this is to pass a function pointer. Functions occupy memory, just like objects. You can refer to this memory address via usual pointer mechanisms. However, unlike objects, you cannot modify the pointed-to function. In this respect, functions are conceptually similar to const objects. You can take the address of functions and invoke them, and that’s about it.

Declaring a Function Pointer

To declare a function pointer, use the following ugly syntax:

return-type (*pointer-name)(arg-type1, arg-type2, ...);

This has the same appearance as a function declaration where the function name is replaced (*pointer-name).

As usual, you can employ the address-of operator & to take the address of a function. This is optional, however; you can simply use the function name as a pointer.

Listing 9-10 illustrates how you can obtain and use function pointers.

#include <cstdio>

float add(float a, int b) {
  return a + b;
}

float subtract(float a, int b) {
  return a - b;
}

int main() {
  const float first{ 100 };
  const int second{ 20 };

  float(*operation)(float, int) {}; ➊
  printf("operation initialized to 0x%p
", operation); ➋

  operation = &add; ➌
  printf("&add = 0x%p
", operation); ➍
  printf("%g + %d = %g
", first, second, operation(first, second)); ➎

  operation = subtract; ➏
  printf("&subtract = 0x%p
", operation); ➐
  printf("%g - %d = %g
", first, second, operation(first, second)); ➑
}
--------------------------------------------------------------------------
operation initialized to 0x0000000000000000 ➋
&add = 0x00007FF6CDFE1070 ➍
100 + 20 = 120 ➎
&subtract = 0x00007FF6CDFE10A0 ➐
100 - 20 = 80 ➑

Listing 9-10: A program illustrating function pointers. (Due to address space layout randomization, the addresses ➍➐ will vary at runtime.)

This listing shows two functions with identical function signatures, add and subtract. Because the function signatures match, pointer types to these functions will also match. You initialize a function pointer operation accepting a float and an int as arguments and returning a float ➊. Next, you print the value of operation, which is nullptr, after initialization ➋.

You then assign the address of add to operation ➌ using the address-of operator and print its new address ➍. You invoke operation and print the result ➎.

To illustrate that you can reassign function pointers, you assign operation to subtract without using the address of operator ➏, print the new value of operation ➐, and finally print the result ➑.

Type Aliases and Function Pointers

Type aliases provide a neat way to program with function pointers. The usage is as follows:

using alias-name = return-type(*)(arg-type1, arg-type2, ...)

You could have defined an operation_func type alias in Listing 9-10, for example:

using operation_func = float(*)(float, int);

This is especially useful if you’ll be using function pointers of the same type; it can really clean up the code.

The Function-Call Operator

You can make user-defined types callable or invocable by overloading the function-call operator operator()(). Such a type is called a function type, and instances of a function type are called function objects. The function-call operator permits any combination of argument types, return types, and modifiers (except static).

The primary reason you might want to make a user-defined type callable is to interoperate with code that expects function objects to use the function-call operator. You’ll find that many libraries, such as the stdlib, use the function-call operator as the interface for function-like objects. For example, in Chapter 19, you’ll learn how to create an asynchronous task with the std::async function, which accepts an arbitrary function object that can execute on a separate thread. It uses the function-call operator as the interface. The committee that invented std::async could have required you to expose, say, a run method, but they chose the function-call operator because it allows generic code to use identical notation to invoke a function or a function object.

Listing 9-11 illustrates the function-call operator’s usage.

struct type-name {
  return-type➊ operator()➋(arg-type1 arg1, arg-type2 arg2, ...➌) {
    // Body of function-call operator
  }
}

Listing 9-11: The function-call operator’s usage

The function-call operator has the special operator() method name ➋. You declare an arbitrary number of arguments ➌, and you also decide the appropriate return type ➊.

When the compiler evaluates a function-call expression, it will invoke the function-call operator on the first operand, passing the remaining operands as arguments. The result of the function-call expression is the result of invoking the corresponding function-call operator.

A Counting Example

Consider the function type CountIf in Listing 9-12, which computes the frequency of a particular char in a null-terminated string.

#include <cstdio>
#include <cstdint>

struct CountIf {
  CountIf(char x) : x{ x } { }➊
  size_t operator()(const char* str➋) const {
    size_t index{}➌, result{};
    while (str[index]) {
      if (str[index] == x) result++; ➍
      index++;
    }
    return result;
  }
private:
  const char x;
};

int main() {
  CountIf s_counter{ 's' }; ➎
  auto sally = s_counter("Sally sells seashells by the seashore."); ➏
  printf("Sally: %zd
", sally);
  auto sailor = s_counter("Sailor went to sea to see what he could see.");
  printf("Sailor: %zd
", sailor);
  auto buffalo = CountIf{ 'f' }("Buffalo buffalo Buffalo buffalo "
                                "buffalo buffalo Buffalo buffalo."); ➐
  printf("Buffalo: %zd
", buffalo);
}
--------------------------------------------------------------------------
Sally: 7
Sailor: 3
Buffalo: 16

Listing 9-12: A function type that counts the number of characters appearing in a null-terminated string

You initialize CountIf objects using a constructor taking a char ➊. You can call the resulting function object as if it were a function taking a null-terminated string argument ➋, because you’ve implemented the function call operator. The function call operator iterates through each character in the argument str using an index variable ➌, incrementing the result variable whenever the character matches the x field ➍. Because calling the function doesn’t modify the state of a CountIf object, you’ve marked it const.

Within main, you’ve initialized the CountIf function object s_counter, which will count the frequency of the letter s ➎. You can use s_counter as if it were a function ➏. You can even initialize a CountIf object and use the function operator directly as an rvalue object ➐. You might find this convenient to do in some settings where, for example, you might only need to invoke the object a single time.

You can employ function objects as partial applications. Listing 9-12 is conceptually similar to the count_if function in Listing 9-13.

#include <cstdio>
#include <cstdint>

size_t count_if(char x➊, const char* str) {
  size_t index{}, result{};
  while (str[index]) {
    if (str[index] == x) result++;
    index++;
  }
  return result;
}

int main() {
  auto sally = count_if('s', "Sally sells seashells by the seashore.");
  printf("Sally: %zd
", sally);
  auto sailor = count_if('s', "Sailor went to sea to see what he could see.");
  printf("Sailor: %zd
", sailor);
  auto buffalo = count_if('f', "Buffalo buffalo Buffalo buffalo "
                               "buffalo buffalo Buffalo buffalo.");
  printf("Buffalo: %zd
", buffalo);
}
--------------------------------------------------------------------------
Sally: 7
Sailor: 3
Buffalo: 16

Listing 9-13: A free function emulating Listing 9-12

The count_if function has an extra argument x ➊, but otherwise it’s almost identical to the function operator of CountIf.

Declaring function types is verbose. You can often reduce the boilerplate substantially with lambda expressions.

Lambda Expressions

Lambda expressions construct unnamed function objects succinctly. The function object implies the function type, resulting in a quick way to declare a function object on the fly. Lambdas don’t provide any additional functionality other than declaring function types the old-fashioned way. But they’re extremely convenient when you need to initialize a function object in only a single context.

Usage

There are five components to a lambda expression:

• captures: The member variables of the function object (that is, the partially applied parameters)
• parameters: The arguments required to invoke the function object
• body: The function object’s code
• specifiers: Elements like constexpr, mutable, noexcept, and [[noreturn]]
• return type: The type returned by the function object

Lambda expression usage is as follows:

[captures➊] (parameters➋) modifiers➎ -> return-type➍ { body➌ }

Only the captures and the body are required; everything else is optional. You’ll learn about each of these components in depth in the next few sections.

Each lambda component has a direct analogue in a function object. To form a bridge between the function objects like CountIf and lambda expressions, look at Listing 9-14, which lists the CountIf function type from Listing 9-12 with annotations that correspond to the analogous portions of the lambda expression in the usage listing.

struct CountIf {
  CountIf(char x) : x{ x } { } ➊
  size_t➍ operator()(const char* str➋) const➎ {
    --snip--➌
  }
private:
  const char x; ➋
};

Listing 9-14: Comparing the CountIf type declaration with a lambda expression

The member variables you set in the constructor of CountIf are analogous to a lambda’s capture ➊. The function-call operator’s arguments ➋, body ➌, and return type ➍ are analogous to the lambda’s parameters, body, and return type. Finally, modifiers can apply to the function-call operator ➎ and the lambda. (The numbers in the Lambda expession usage example and Listing 9-14 correspond.)

Lambda Parameters and Bodies

Lambda expressions produce function objects. As function objects, lambdas are callable. Most of the time, you’ll want your function object to accept parameters upon invocation.

The lambda’s body is just like a function body: all of the parameters have function scope.

You declare lambda parameters and bodies using essentially the same syntax that you use for functions.

For example, the following lambda expression yields a function object that will square its int argument:

[](int x) { return x*x; }

The lambda takes a single int x and uses it within the lambda’s body to perform the squaring.

Listing 9-15 employs three different lambdas to transform the array 1, 2, 3.

#include <cstdio>
#include <cstdint>

template <typename Fn>
void transform(Fn fn, const int* in, int* out, size_t length) { ➊
  for(size_t i{}; i<length; i++) {
    out[i] = fn(in[i]); ➋
  }
}

int main() {
  const size_t len{ 3 };
  int base[]{ 1, 2, 3 }, a[len], b[len], c[len];
  transform([](int x) { return 1; }➌, base, a, len);
  transform([](int x) { return x; }➍, base, b, len);
  transform([](int x) { return 10*x+5; }➎, base, c, len);
  for (size_t i{}; i < len; i++) {
    printf("Element %zd: %d %d %d
", i, a[i], b[i], c[i]);
  }
}
--------------------------------------------------------------------------
Element 0: 1 1 15
Element 1: 1 2 25
Element 2: 1 3 35

Listing 9-15: Three lambdas and a transform function

The transform template function ➊ accepts four arguments: a function object fn, an in array and an out array, and the corresponding length of those arrays. Within transform, you invoke fn on each element of in and assign the result to the corresponding element of out ➋.

Within main, you declare a base array 1, 2, 3 that will be used as the in array. In the same line you also declare three uninitialized arrays a, b, and c, which will be used as the out arrays. The first call to transform passes a lambda ([](int x) { return 1; }) that always returns 1 ➌, and the result is stored into a. (Notice that the lambda didn’t need a name!) The second call to transform ([](int x) { return x; }) simply returns its argument ➍, and the result is stored into b. The third call to transform multiplies the argument by 10 and adds 5 ➎. The result is stored in c. You then print the output into a matrix where each column illustrates the transform that was applied to the different lambdas in each case.

Notice that you declared transform as a template function, allowing you to reuse it with any function object.

Default Arguments

You can provide default arguments to a lambda. Default lambda parameters behave just like default function parameters. The caller can specify values for default parameters, in which case the lambda uses the caller-provided values. If the caller doesn’t specify a value, the lambda uses the default.

Listing 9-16 illustrates the default argument behavior.

#include <cstdio>

int main() {
  auto increment = [](auto x, int y = 1➊) { return x + y; };
  printf("increment(10)    = %d
", increment(10)); ➋
  printf("increment(10, 5) = %d
", increment(10, 5)); ➌
}
--------------------------------------------------------------------------
increment(10)    = 11 ➋
increment(10, 5) = 15 ➌

Listing 9-16: Using default lambda parameters

The increment lambda has two parameters, x and y. But the y parameter is optional because it has the default argument 1 ➊. If you don’t specify an argument for y when you call the function ➋, increment returns 1 + x. If you do call the function with an argument for y ➌, that value is used instead.

Generic Lambdas

Generic lambdas are lambda expression templates. For one or more parameters, you specify auto rather than a concrete type. These auto types become template parameters, meaning the compiler will stamp out a custom instantiation of the lambda.

Listing 9-17 illustrates how to assign a generic lambda into a variable and then use the lambda in two different template instantiations.

#include <cstdio>
#include <cstdint>

template <typename Fn, typename T➊>
void transform(Fn fn, const T* in, T* out, size_t len) {
  for(size_t i{}; i<len; i++) {
    out[i] = fn(in[i]);
  }
}

int main() {
  constexpr size_t len{ 3 };
  int base_int[]{ 1, 2, 3 }, a[len]; ➋
  float base_float[]{ 10.f, 20.f, 30.f }, b[len]; ➌
  auto translate = [](auto x) { return 10 * x + 5; }; ➍
  transform(translate, base_int, a, l); ➎
  transform(translate, base_float, b, l); ➏

  for (size_t i{}; i < l; i++) {
    printf("Element %zd: %d %f
", i, a[i], b[i]);
  }
}
--------------------------------------------------------------------------
Element 0: 15 105.000000
Element 1: 25 205.000000
Element 2: 35 305.000000

Listing 9-17: Using a generic lambda

You add a second template parameter to transform ➊, which you use as the pointed-to type of in and out. This allows you to apply transform to arrays of any type, not just of int types. To test out the upgraded transform template, you declare two arrays with different pointed-to types: int ➋ and float ➌. (Recall from Chapter 3 that the f in 10.f specifies a float literal.) Next, you assign a generic lambda expression to translate ➍. This allows you to use the same lambda for each instantiation of transform: when you instantiate with base_int ➎ and with base_float ➏.

Without a generic lambda, you’d have to declare the parameter types explicitly, like the following:

--snip–
  transform([](int x) { return 10 * x + 5; }, base_int, a, l); ➎
  transform([](double x) { return 10 * x + 5; }, base_float, b, l); ➏

So far, you’ve been leaning on the compiler to deduce the return types of your lambdas. This is especially useful for generic lambdas, because often the lambda’s return type will depend on its parameter types. But you can explicitly state the return type if you want.

Lambda Return Types

The compiler deduces a lambda’s return type for you. To take over from the compiler, you use the arrow -> syntax, as in the following:

[](int x, double y) -> double { return x + y; }

This lambda expression accepts an int and a double and returns a double.

You can also use decltype expressions, which can be useful with generic lambdas. For example, consider the following lambda:

[](auto x, double y) -> decltype(x+y) { return x + y; }

Here you’ve explicitly declared that the return type of the lambda is whatever type results from adding an x to a y.

You’ll rarely need to specify a lambda’s return type explicitly.

A far more common requirement is that you must inject an object into a lambda before invocation. This is the role of lambda captures.

Lambda Captures

Lambda captures inject objects into the lambda. The injected objects help to modify the behavior of the lambda.

Declare a lambda’s capture by specifying a capture list within brackets []. The capture list goes before the parameter list, and it can contain any number of comma-separated arguments. You then use these arguments within the lambda’s body.

A lambda can capture by reference or by value. By default, lambdas capture by value.

A lambda’s capture list is analogous to a function type’s constructor. Listing 9-18 reformulates CountIf from Listing 9-12 as the lambda s_counter.

#include <cstdio>
#include <cstdint>

int main() {
  char to_count{ 's' }; ➊
  auto s_counter = [to_count➋](const char* str) {
    size_t index{}, result{};
    while (str[index]) {
      if (str[index] == to_count➌) result++;
      index++;
    }
    return result;
  };
  auto sally = s_counter("Sally sells seashells by the seashore."➍);
  printf("Sally: %zd
", sally);
  auto sailor = s_counter("Sailor went to sea to see what he could see.");
  printf("Sailor: %zd
", sailor);
}
--------------------------------------------------------------------------
Sally: 7
Sailor: 3

Listing 9-18: Reformulating CountIf from Listing 9-12 as a lambda

You initialize a char called to_count to the letter s ➊. Next, you capture to_count within the lambda expression assigned to s_counter ➋. This makes to_count available within the body of the lambda expression ➌.

To capture an element by reference rather than by value, prefix the captured object’s name with an ampersand &. Listing 9-19 adds a capture reference to s_counter that keeps a running tally across lambda invocations.

#include <cstdio>
#include <cstdint>

int main() {
  char to_count{ 's' };
  size_t tally{};➊
  auto s_counter = [to_count, &tally➋](const char* str) {
    size_t index{}, result{};
    while (str[index]) {
      if (str[index] == to_count) result++;
      index++;
    }
    tally += result;➌
    return result;
  };
  printf("Tally: %zd
", tally); ➍
  auto sally = s_counter("Sally sells seashells by the seashore.");
  printf("Sally: %zd
", sally);
  printf("Tally: %zd
", tally); ➎
  auto sailor = s_counter("Sailor went to sea to see what he could see.");
  printf("Sailor: %zd
", sailor);
  printf("Tally: %zd
", tally); ➏
}
--------------------------------------------------------------------------
Tally: 0 ➍
Sally: 7
Tally: 7 ➎
Sailor: 3
Tally: 10 ➏

Listing 9-19: Using a capture reference in a lambda

You initialize the counter variable tally to zero ➊, and then the s_counter lambda captures tally by reference (note the ampersand &) ➋. Within the lambda’s body, you add a statement to increment tally by an invocation’s result before returning ➌. The result is that tally will track the total count no matter how many times you invoke the lambda. Before the first s_counter invocation, you print the value of tally ➍ (which is still zero). After you invoke s_counter with Sally sells seashells by the seashore., you have a tally of 7 ➎. The last invocation of s_counter with Sailor went to sea to see what he could see. returns 3, so the value of tally is 7 + 3 = 10 ➏.

Default Capture

So far, you’ve had to capture each element by name. Sometimes this style of capturing is called named capture. If you’re lazy, you can capture all automatic variables used within a lambda using default capture. To specify a default capture by value within a capture list, use a lone equal sign =. To specify a default capture by reference, use a lone ampersand &.

For example, you could “simplify” the lambda expression in Listing 9-19 to perform a default capture by reference, as demonstrated in Listing 9-20.

--snip--
  auto s_counter = [&➊](const char* str) {
    size_t index{}, result{};
    while (str[index]) {
      if (str[index] == to_count➋) result++;
      index++;
    }
    tally➌ += result;
    return result;
  };
--snip--

Listing 9-20: Simplifying a lambda expression with a default capture by reference

You specify a default capture by reference ➊, which means any automatic variables in the body of the lambda expression get captured by reference. There are two: to_count ➋ and tally ➌.

If you compile and run the refactored listing, you’ll obtain identical output. However, notice that to_count is now captured by reference. If you accidentally modify it within the lambda expression’s body, the change will occur across lambda invocations as well as within main (where to_count is an automatic variable).

What would happen if you performed a default capture by value instead? You would only need to change the = to an & in the capture list, as demonstrated in Listing 9-21.

--snip--
  auto s_counter = [=➊](const char* str) {
    size_t index{}, result{};
    while (str[index]) {
      if (str[index] == to_count➋) result++;
      index++;
    }
    tally➌ += result;
    return result;
  };
--snip--

Listing 9-21: Modifying Listing 9-20 to capture by value instead of by reference (This code doesn't compile.)

You change the default capture to be by value ➊. The to_count capture is unaffected ➋, but attempting to modify tally results in a compiler error ➌. You’re not allowed to modify variables captured by value unless you add the mutable keyword to the lambda expression. The mutable keyword allows you to modify value-captured variables. This includes calling non-const methods on that object.

Listing 9-22 adds the mutable modifier and has a default capture by value.

#include <cstdio>
#include <cstdint>

int main() {
  char to_count{ 's' };
  size_t tally{};
  auto s_counter = [=➊](const char* str) mutable➋ {
    size_t index{}, result{};
    while (str[index]) {
      if (str[index] == to_count) result++;
      index++;
    }
    tally += result;
    return result;
  };
  auto sally = s_counter("Sally sells seashells by the seashore.");
  printf("Tally: %zd
", tally); ➌
  printf("Sally: %zd
", sally);
  printf("Tally: %zd
", tally); ➍
  auto sailor = s_counter("Sailor went to sea to see what he could see.");
  printf("Sailor: %zd
", sailor);
  printf("Tally: %zd
", tally); ➎
}
--------------------------------------------------------------------------
Tally: 0
Sally: 7
Tally: 0
Sailor: 3
Tally: 0

Listing 9-22: A mutable lambda expression with a default capture by value

You declare a default capture by value ➊, and you make the lambda s_counter mutable ➋. Each of the three times you print tally ➌➍➎, you get a zero value. Why?

Because tally gets copied by value (via the default capture), the version in the lambda is, in essence, an entirely different variable that just happens to have the same name. Modifications to the lambda’s copy of tally don’t affect the automatic tally variable of main. The tally in main() is initialized to zero and never gets modified.

It’s also possible to mix a default capture with a named capture. You could, for example, default capture by reference and copy to_count by value using the following formulation:

  auto s_counter = [&➊,to_count➋](const char* str) {
    --snip--
  };

This specifies a default capture by reference ➊ and to_count ➋ capture by value.

Although performing a default capture might seem like an easy shortcut, refrain from using it. It’s far better to declare captures explicitly. If you catch yourself saying “I’ll just use a default capture because there are too many variables to list out,” you probably need to refactor your code.

Initializer Expressions in Capture Lists

Sometimes you want to initialize a whole new variable within a capture list. Maybe renaming a captured variable would make a lambda expression’s intent clearer. Or perhaps you want to move an object into a lambda and therefore need to initialize a variable.

To use an initializer expression, just declare the new variable’s name followed by an equal sign and the value you want to initialize your variable with, as Listing 9-23 demonstrates.

  auto s_counter = [&tally➊,my_char=to_count➋](const char* str) {
    size_t index{}, result{};
    while (str[index]) {
      if (str[index] == my_char➌) result++;
    --snip--
  };

Listing 9-23: Using an initializer expression within a lambda capture

The capture list contains a simple named capture where you have tally by reference ➊. The lambda also captures to_count by value, but you’ve elected to use the variable name my_char instead ➋. Of course, you’ll need to use the name my_char instead of to_count inside the lambda ➌.

Capturing this

Sometimes lambda expressions have an enclosing class. You can capture an enclosing object (pointed-to by this) by value or by reference using either [*this] or [this], respectively.

Listing 9-24 implements a LambdaFactory that generates counting lambdas and keeps track of a tally.

#include <cstdio>
#include <cstdint>

struct LambdaFactory {
  LambdaFactory(char in) : to_count{ in }, tally{} { }
  auto make_lambda() { ➊
    return [this➋](const char* str) {
      size_t index{}, result{};
      while (str[index]) {
        if (str[index] == to_count➌) result++;
        index++;
      }
      tally➍ += result;
      return result;
    };
  }
  const char to_count;
  size_t tally;
};

int main() {
  LambdaFactory factory{ 's' }; ➎
  auto lambda = factory.make_lambda(); ➏
  printf("Tally: %zd
", factory.tally);
  printf("Sally: %zd
", lambda("Sally sells seashells by the seashore."));
  printf("Tally: %zd
", factory.tally);
  printf("Sailor: %zd
", lambda("Sailor went to sea to see what he could see."));
  printf("Tally: %zd
", factory.tally);
}
--------------------------------------------------------------------------
Tally: 0
Sally: 7
Tally: 7
Sailor: 3
Tally: 10

Listing 9-24: A LambdaFactory illustrating the use of this capture

The LambdaFactory constructor takes a single character and initializes the to_count field with it. The make_lambda ➊ method illustrates how you can capture this by reference ➋ and use the to_count ➌ and tally ➍ member variables within the lambda expression.

Within main, you initialize a factory ➎ and make a lambda using the make_lambda method ➏. The output is identical to Listing 9-19, because you capture this by reference and state of tally persists across invocations of lambda.

Clarifying Examples

There are a lot of possibilities with capture lists, but once you have a command of the basics–capturing by value and by reference–there aren’t many surprises. Table 9-2 provides short, clarifying examples that you can use for future reference.

Table 9-2: Clarifying Examples of Lambda Capture Lists

constexpr Lambda Expressions

All lambda expressions are constexpr as long as the lambda can be invoked at compile time. You can optionally make the constexpr declaration explicit, as in the following:

[] (int x) constexpr { return x * x; }

You should mark a lambda constexpr if you want to make sure that it meets all constexpr requirements. As of C++17, this means no dynamic memory allocations and no calling non-constexpr functions, among other restrictions. The standards committee plans to loosen these restrictions with each release, so if you write a lot of code using constexpr, be sure to brush up on the latest constexpr constraints.

std::function

Sometimes you just want a uniform container for storing callable objects. The std::function class template from the <functional> header is a polymorphic wrapper around a callable object. In other words, it’s a generic function pointer. You can store a static function, a function object, or a lambda into a std::function.

With functions, you can:

• Invoke without the caller knowing the function’s implementation
• Assign, move, and copy
• Have an empty state, similar to a nullptr

Declaring a Function

To declare a function, you must provide a single template parameter containing the function prototype of the callable object:

std::function<return-type(arg-type-1, arg-type-2, etc.)>

The std::function class template has a number of constructors. The default constructor constructs a std::function in empty mode, meaning it contains no callable object.

Empty Functions

If you invoke a std::function with no contained object, std::function will throw a std::bad_function_call exception. Consider Listing 9-25.

#include <cstdio>
#include <functional>

int main() {
    std::function<void()> func; ➊
    try {
        func(); ➋
    } catch(const std::bad_function_call& e) {
        printf("Exception: %s", e.what()); ➌
    }
}
--------------------------------------------------------------------------
Exception: bad function call ➌

Listing 9-25: The default std::function constructor and the std::bad_function_call exception

You default-construct a std::function ➊. The template parameter void() denotes a function taking no arguments and returning void. Because you didn’t fill func with a callable object, it’s in an empty state. When you invoke func ➋, it throws a std::bad_function_call, which you catch and print ➌.

Assigning a Callable Object to a Function

To assign a callable object to a function, you can either use the constructor or assignment operator of function, as in Listing 9-26.

#include <cstdio>
#include <functional>

void static_func() { ➊
  printf("A static function.
");
}

int main() {
  std::function<void()> func { [] { printf("A lambda.
"); } }; ➋
  func(); ➌
  func = static_func; ➍
  func(); ➎
}
--------------------------------------------------------------------------
A lambda. ➌
A static function. ➎

Listing 9-26: Using the constructor and assignment operator of function

You declare the static function static_func that takes no arguments and returns void ➊. In main, you create a function called func ➋. The template parameter indicates that a callable object contained by func takes no arguments and returns void. You initialize func with a lambda that prints the message A lambda. You invoke func immediately afterward ➌, invoking the contained lambda and printing the expected message. Next, you assign static_func to func, which replaces the lambda you assigned upon construction ➍. You then invoke func, which invokes static_func rather than the lambda, so you see A static function. printed ➎.

An Extended Example

You can construct a function with callable objects, as long as that object supports the function semantics implied by the template parameter of function.

Listing 9-27 uses an array of std::function instances and fills it with a static function that counts spaces, a CountIf function object from Listing 9-12, and a lambda that computes string length.

#include <cstdio>
#include <cstdint>
#include <functional>

struct CountIf {
  --snip--
};

size_t count_spaces(const char* str) {
  size_t index{}, result{};
  while (str[index]) {
    if (str[index] == ' ') result++;
    index++;
  }
  return result;
}

std::function➊<size_t(const char*)➋> funcs[]{
  count_spaces, ➌
  CountIf{ 'e' }, ➍
  [](const char* str) { ➎
    size_t index{};
    while (str[index]) index++;
    return index;
  }
};

auto text = "Sailor went to sea to see what he could see.";

int main() {
  size_t index{};
  for(const auto& func : funcs➏) {
    printf("func #%zd: %zd
", index++, func(text)➐);
  }
}
--------------------------------------------------------------------------
func #0: 9 ➌
func #1: 7 ➍
func #2: 44 ➎

Listing 9-27: Using a std::function array to iterate over a uniform collection of callable objects with varying underlying types

You declare a std::function array ➊ with static storage duration called funcs. The template argument is the function prototype for a function taking a const char* and returning a size_t ➋. In the funcs array, you pass in a static function pointer ➌, a function object ➍, and a lambda ➎. In main, you use a range-based for loop to iterate through each function in funcs ➏. You invoke each function func with the text Sailor went to sea to see what he could see. and print the result.

Notice that, from the perspective of main, all the elements in funcs are the same: you just invoke them with a null-terminated string and get back a size_t ➐.

The main Function and the Command Line

All C++ programs must contain a global function with the name main. This function is defined as the program’s entry point, the function invoked at program startup. Programs can accept any number of environment-provided arguments called command line parameters upon startup.

Users pass command line parameters to programs to customize their behavior. You’ve probably used this feature when executing command line programs, as in the copy (on Linux: cp) command:

$ copy file_a.txt file_b.txt

When invoking this command, you instruct the program to copy file_a.txt into file_b.txt by passing these values as command line parameters. As with command line programs you might be used to, it’s possible to pass values as command line parameters to your C++ programs.

You can choose whether your program handles command line parameters by how you declare main.

The Three main Overloads

You can access command line parameters within main by adding arguments to your main declaration.

There are three valid varieties of overload for main, as shown in Listing 9-28.

int main(); ➊
int main(int argc, char* argv[]); ➋
int main(int argc, char* argv[], impl-parameters); ➌

Listing 9-28: The valid overloads for main

The first overload ➊ takes no parameters, which is the way you’ve been using main() in this book so far. Use this form if you want to ignore any arguments provided to your program.

The second overload ➋ accepts two parameters, argc and argv. The first argument, argc, is a non-negative number corresponding to the number of elements in argv. The environment calculates this automatically: you don’t have to provide the number of elements in argc. The second argument, argv, is an array of pointers to null-terminated strings that corresponds to an argument passed in from the execution environment.

The third overload ➌: is an extension of the second overload ➋: it accepts an arbitrary number of additional implementation parameters. This way, the target platform can offer some additional arguments to the program. Implementation parameters aren’t common in modern desktop environments.

Usually, an operating system passes the full path to the program’s executable as the first command line argument. This behavior depends on your operating environment. On macOS, Linux, and Windows, the executable’s path is the first argument. The format of this path depends on the operating system. (Chapter 17 discusses filesystems in depth.)

Exploring Program Parameters

Let’s build a program to explore how the operating system passes parameters to your program. Listing 9-29 prints the number of command line arguments and then prints the index and value of the arguments on each line.

#include <cstdio>
#include <cstdint>

int main(int argc, char** argv) { ➊
  printf("Arguments: %d
", argc); ➋
  for(size_t i{}; i<argc; i++) {
    printf("%zd: %s
", i, argv[i]); ➌
  }
}

Listing 9-29: A program that prints the command line arguments. Compile this program as list_929.

You declare main with the argc/argv overload, which makes command line parameters available to your program ➊. First, you print the number of command line arguments via argc ➋. Then you loop through each argument, printing its index and its value ➌.

Let’s look at some sample output (on Windows 10 x64). Here is one program invocation:

$ list_929 ➊
Arguments: 1 ➋
0: list_929.exe ➌

Here, you provide no additional command line arguments aside from the name of the program, list_929 ➊. (Depending on how you compiled the listing, you should replace this with the name of your executable.) On a Windows 10 x64 machine, the result is that your program receives a single argument ➋, the name of the executable ➌.

And here is another invocation:

$ list_929 Violence is the last refuge of the incompetent. ➊
Arguments: 9
0: list_929.exe
1: Violence
2: is
3: the
4: last
5: refuge
6: of
7: the
8: incompetent.

Here, you provide additional program arguments: Violence is the last refuge of the incompetent. ➊. You can see from the output that Windows has split the command line by spaces, resulting in a total of nine arguments.

In major desktop operating systems, you can force the operating system to treat such a phrase as a single argument by enclosing it within quotes, as in the following:

$ list_929 "Violence is the last refuge of the incompetent."
Arguments: 2
0: list_929.exe
1: Violence is the last refuge of the incompetent.

A More Involved Example

Now that you know how to process command line input, let’s consider a more involved example. A histogram is an illustration that shows a distribution’s relative frequency. Let’s build a program that computes a histogram of the letter distribution of the command line arguments.

Start with two helper functions that determine whether a given char is an uppercase letter or a lowercase letter:

constexpr char pos_A{ 65 }, pos_Z{ 90 }, pos_a{ 97 }, pos_z{ 122 };
constexpr bool within_AZ(char x) { return pos_A <= x && pos_Z >= x; } ➊
constexpr bool within_az(char x) { return pos_a <= x && pos_z >= x; } ➋

The pos_A, pos_Z, pos_a, and pos_z constants contain the ASCII values of the letters A, Z, a, and z respectively (refer to the ASCII chart in Table 2-4). The within_AZ function determines whether some char x is an uppercase letter by determining whether its value is between pos_A and pos_Z inclusive ➊. The within_az function does the same for lowercase letters ➋.

Now that you have some elements for processing ASCII data from the command line, let’s build an AlphaHistogram class that can ingest command line elements and store character frequencies, as shown in Listing 9-30.

struct AlphaHistogram {
  void ingest(const char* x); ➊
  void print() const; ➋
private:
  size_t counts[26]{}; ➌
};

Listing 9-30: An AlphaHistogram that ingests command line elements

An AlphaHistogram will store the frequency of each letter in the counts array ➌. This array initializes to zero whenever an AlphaHistogram is constructed. The ingest method will take a null-terminated string and update counts appropriately ➊. Then the print method will display the histogram information stored in counts ➋.

First, consider the implementation of ingest in Listing 9-31.

void AlphaHistogram::ingest(const char* x) {
  size_t index{}; ➊
  while(const auto c = x[index]) { ➋
    if (within_AZ(c)) counts[c - pos_A]++; ➌
    else if (within_az(c)) counts[c - pos_a]++; ➍
    index++; ➎
  }
}

Listing 9-31: An implementation of the ingest method

Because x is a null-terminated string, you don’t know its length ahead of time. So, you initialize an index variable ➊ and use a while loop to extract a single char c at a time ➋. This loop will terminate if c is null, which is the end of the string. Within the loop, you use the within_AZ helper function to determine whether c is an uppercase letter ➌. If it is, you subtract pos_A from c. This normalizes an uppercase letter to the interval 0 to 25 to correspond with counts. You do the same check for lowercase letters using the within_az helper function ➍, and you update counts in case c is lowercase. If c is neither lowercase nor uppercase, counts is unaffected. Finally, you increment index before continuing to loop ➎.

Now, consider how to print counts, as shown in Listing 9-32.

void AlphaHistogram::print() const {
  for(auto index{ pos_A }; index <= pos_Z; index++) { ➊
    printf("%c: ", index); ➋
    auto n_asterisks = counts[index - pos_A]; ➌
    while (n_asterisks--) printf("*"); ➍
    printf("
"); ➎
  }
}

Listing 9-32: An implementation of the print method

To print the histogram, you loop over each letter from A to Z ➊. Within the loop, you first print the index letter ➋, and then determine how many asterisks to print by extracting the correct letter out of counts ➌. You print the correct number of asterisks using a while loop ➍, and then you print a terminating newline ➎.

Listing 9-33 shows AlphaHistogram in action.

#include <cstdio>
#include <cstdint>

constexpr char pos_A{ 65 }, pos_Z{ 90 }, pos_a{ 97 }, pos_z{ 122 };
constexpr bool within_AZ(char x) { return pos_A <= x && pos_Z >= x; }
constexpr bool within_az(char x) { return pos_a <= x && pos_z >= x; }

struct AlphaHistogram {
  --snip--
};

int main(int argc, char** argv) {
  AlphaHistogram hist;
  for(size_t i{ 1 }; i<argc; i++) { ➊
    hist.ingest(argv[i]); ➋
  }
  hist.print(); ➌
}
--------------------------------------------------------------------------
$ list_933 The quick brown fox jumps over the lazy dog
A: *
B: *
C: *
D: *
E: ***
F: *
G: *
H: **
I: *
J: *
K: *
L: *
M: *
N: *
O: ****
P: *
Q: *
R: **
S: *
T: **
U: **
V: *
W: *
X: *
Y: *
Z: *

Listing 9-33: A program illustrating AlphaHistogram

You iterate over each command line argument after the program name ➊, passing each into the ingest method of your AlphaHistogram object ➋. Once you’ve ingested them all, you print the histogram ➌. Each line corresponds to a letter, and the asterisks show the absolute frequency of the corresponding letter. As you can see, the phrase The quick brown fox jumps over the lazy dog contains each letter in the English alphabet.

Exit Status

The main function can return an int corresponding to the exit status of the program. What the values represent is environment defined. On modern desktop systems, for example, a zero return value corresponds with a successful program execution. If no return statement is explicitly given, an implicit return 0 is added by the compiler.

Summary

This chapter took a deeper look at functions, including how to declare and define them, how to use the myriad keywords available to you to modify function behavior, how to specify return types, how overload resolution works, and how to take a variable number of arguments. After a discussion of how you take pointers to functions, you explored lambda expressions and their relationship to function objects. Then you learned about the entry point for your programs, the main function, and how to take command line arguments.

template <typename Fn, typename In, typename Out>
constexpr Out fold(Fn function, In* input, size_t length, Out initial);

int main() {
  int data[]{ 100, 200, 300, 400, 500 };
  size_t data_len = 5;
  auto sum = fold([](auto x, auto y) { return x + y; }, data, data_len,
0);
  print("Sum: %d
", sum);
}

template <typename Fn, typename In, typename Out>
constexpr bool all(Fn function, In* input, size_t length);

int main() {
  int data[]{ 100, 200, 300, 400, 500 };
  size_t data_len = 5;
  auto all_gt100 = all([](auto x) { return x > 100; }, data, data_len);
  if(all_gt100) printf("All elements greater than 100.
");
}