function call, <stdarg><, >va_list, va_start, va_end, va_arg
Throughout most of the textbook, I use ellipses to denote code omitted for brevity. However, in the context of variable-length argument lists, the ellipses are part of the required syntax, denoting the variable number of arguments.
Typically, when a program calls a function, it must pass a fixed, predetermined number of arguments to it. In the case of default arguments, the function specifies values that are substituted for missing arguments, bringing the argument count up to the necessary number. Infrequently, programmers must create functions whose number of arguments is flexible or not predetermined at compile time - functions with a variable number of arguments. C++ inherits from C a mechanism - implemented by the preprocessor expanding a set of macros - for creating such functions.
<cstdarg> (C++) or <stdarg.h> (C)
The header files specifying the variable-length-argument-list macros. Programs must include one of the files before using the macros.
va_list
The "data type" used to define a variable-length argument list. The macro creates an argument list that the program passes to the function at runtime.
va_start
Initializes the variables supporting the variable-length argument list. Requires two parameters:
the variable-length argument created by va_list, and
the name of the first argument.
va_end
Finish using the variable-length argument list; requires one parameter: the variable-length argument created by va_list
va_arg
Extracts an argument from the variable-length argument list. Requires two parameters:
the variable-length argument created by va_list, and
the "real" data type of the next argument. The following examples illustrate what I mean by "real" data type.
The variable-length-argument-list macros.
The variable-length-argument-list mechanism consists of a header file specifying the macros and the macros themselves. The mechanism uses macros because it requires textual information contained in the source code that is lost when the compiler component translates the source to machine code (see The C++ compiler system).
Function calls passing a variable number of arguments must signal to the function the actual number of arguments passed. Programmers typically use two techniques to pass the count in the first argument. The first technique explicitly passes the number as the first argument, while the second encodes the number as a string of characters denoting the data types of the remaining arguments.
Explicit number of arguments:
function(5, "see", "the", "quick", "red", "fox");
The number of arguments encoded as a type-string (similar to the C printf function):
function("dfcs", 10, 3.14, 'X', "Hello world");
d: decimal or integer (int, long, or short)
f: floating point (double or float)
c: character
s: string (i.e., a char* - C-strings are covered in chapter 8)
Function calls with a variable number of arguments.
Function calls with a variable number of arguments begin with one fixed argument, and the corresponding function definitions begin with one fixed parameter followed by an ellipsis (this situation is the only one the text describes where the ellipses are part of the C++ syntax). The macros use the address of the first argument in conjunction with address arithmetic to locate the subsequent arguments in the list. Fortunately, the macros do the arithmetic, hiding the calculation's complexity from programmers.
Variable-Length Argument List: Argument Number Example
#include <iostream>
#include <cstdarg>
using namespace std;
void average(int n, ...);
int main()
{
average(5, 1, 2, 3, 4, 5);
average(10, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10);
return 0;
}
// Technique #1 -- the fixed argument specifies the number of arguments.
void average(int n, ...) // the ... are part of the C++ syntax
{
va_list args; // create a variable-length argument list
double sum = 0;
va_start(args, n); // begin accessing variable-length arguments
for (int i = 0; i < n; i++)
sum += va_arg(args, int); // get an argument from the list
cout << "Average: " << sum / n << endl;
va_end(args); // finish accessing variable-length arguments
}
Defining and calling a function with a variable number of arguments.
The fixed arguments, the "5" and "10" highlighted in red, denote the number of variable-length arguments following the fixed argument.
Variable-Length Argument List: String Encoding Example
#include <iostream>
#include <cstdarg>
using namespace std;
void print(char* list, ...);
int main()
{
print("fsfd", 3.144159, "Hello world", 2.7, 100);
print("ss", "hello", "world");
return 0;
}
// Technique #2 -- the fixed argument encodes the number and type of arguments.
void print(char* list, ...)
{
va_list args;va_start(args, list);
char c;
while(c = *list++)
switch(c)
{
case 's' : cout << va_arg(args, char*) << endl;
break;
case 'd' : cout << va_arg(args, int) << endl;
break;
case 'f' : cout << va_arg(args, double) << endl;
break;
}
va_end(args);
}
Defining and calling a function with a string-encoded variable-length argument list. The fixed argument, highlighted in red, in each function call encodes the number and type of each argument that follows it. The examples follow the "standard" encoding list above. So, "fsfd" denotes four arguments (left to right): floating point, string, floating point, and decimal; "ss" denotes two strings. The example uses string literals throughout, but it also allows string variables. (If you want to look ahead, please see C-strings.)