Variadic function

"Varargs" redirects here. For the varargs.h library in C, see varargs.h.

In computer programming, a variadic function is a function of variable arity; that is, one which can take different numbers of arguments. Support for variadic functions differs widely among programming languages.

There are many mathematical and logical operations which come across naturally as variadic functions. For instance, the summing of numbers or the concatenation of strings or other sequences are operations that can logically apply to any number of operands.

Another operation which has been implemented as a variadic function in many languages is output formatting. The C function printf and the Common Lisp function format are two such examples. Both take one argument which specifies the formatting of the output, and any number of arguments which provide the values to be formatted.

Variadic functions can expose type-safety problems in some languages. For instance, C's printf, if used incautiously, can give rise to a class of security holes known as format string attacks. The attack is possible because the language support for variadic functions is not type-safe; it permits the function to attempt to pop more arguments off the stack than were placed there -- corrupting the stack and leading to unexpected behavior.

Variadic functionality can be considered complementary to the apply function, which takes a function and a list/sequence/array as arguments and then calls the function once, with the arguments being the elements of the list.

Specific implementations

The following provides an overview of specific implementations in different programming languages and environments.

Variadic functions in Common Lisp

Common Lisp uses the &rest argument specifier to implement variadic functions. At execution time, the &rest variable collects all following arguments into one list. For example:

(defun average (&rest args)
  (when args
    (/ (apply #'+ args) (length args))))

Note that this uses the standard lisp add function which itself is a variadic function.

Common Lisp also provides the &body specifier for situations where multiple statements of code are being passed in as parameters (generally when implementing syntactic macros). While such situations can equivalently be handled by &rest, &body is preferred because it conveys the author's intent more specifically. For example, here is a re-implementation of prog1, a macro that returns the result of the first of a block of statements:

(defmacro prog1-2 (&body statements)
  (let ((varname (gensym)))
    ,(let ((,varname ,(car statements)))
      ,@(cdr statements)
      ,varname)))

Like Python, Common Lisp provides a facility for optional parameters and named parameters (also called dictionary parameters). For instance, consider this function whose second parameter takes a default value if unspecified:

(defun plus (n &optional (number-to-add 1))
  (+ n number-to-add))

When invoked with a single parameter N, the result will be N + 1. When invoked with two parameters X and Y, the result will be X + Y.

Parameters may also be given out-of-order. Consider, for instance, a function that constructs a tuple representing a data item. Such a function could be implemented like this:

(defun construct-data-record (&key (name "") (phone "") (fax "") (address ""))
  (list name phone fax address))

(construct-data-record :name "Name")                                     ; => ("Name" "" "" "")
(construct-data-record :address "10 Some Street" :phone "555-555-5555")  ; => ("" "555-555-5555" "" "10 Some Street")
(construct-data-record)                                                  ; => ("" "" "" "")

Variadic functions in C, Objective-C, C++, and D

To portably implement variadic functions in the C programming language, the standard stdarg.h header file should be used. The older varargs.h header has been deprecated in favor of stdarg.h. In C++, the header file cstdarg should be used.

To create a variadic function, an ellipsis (...) must be placed at the end of a parameter list. Inside the body of the function, a variable of type va_list must be defined. Then the macros va_start(va_list, last fixed param), va_arg(va_list, cast type), va_end(va_list) can be used. For example:

#include <stdarg.h>

double average(int count, ...)
{
    va_list ap;
    int j;
    double tot = 0;
    va_start(ap, count); //Requires the last fixed parameter (to get the address)
    for(j=0; j<count; j++)
        tot+=va_arg(ap, double); //Requires the type to cast to. Increments ap to the next argument.
    va_end(ap);
    return tot/count;
}

This will compute the average of an arbitrary number of arguments. Note that neither the number nor types of arguments are known to the function. In the case of the above function, the types are hard-coded to be double, and the number of arguments is passed in separately. In some other cases, for example printf, the number and types of arguments are figured out from a format string. In both cases, this depends on the programmer to actually supply the correct information. If fewer arguments are passed in than the function believes, or the types of arguments are incorrect, this could cause it to read into invalid areas of memory and can lead to vulnerabilities like the format string attack.

Objective-C uses the same varargs functionality as C. Like C, it has no way of knowing the number or types of the arguments. When the arguments are all objects, the convention is that, if the number of arguments is undetermined, then the list must be "terminated" with nil. Functions that follow this convention include the constructors of data structures that take an undetermined number of elements, like [NSArray arrayWithObjects:...].

#include <stdarg.h>

void logObjects(id firstObject, ...) // <-- there is always at least one arg, "nil", so this is valid, even for "empty" list
{
  va_list args;
  va_start(args, firstObject);
  id obj;
  for (obj = firstObject; obj != nil; obj = va_arg(args, id))
    NSLog(@"%@", obj);
  va_end(args);
}

// This function can be called with any number or type of objects, as long as you terminate it with "nil":
logObjects(@"foo", [NSNumber numberWithInt:4], @"bar", nil);

The variadic function feature is going to be present in the upcoming C++ language standard, C++0x; this feature is called variadic templates. This allows the creation of variadic template classes and variadic template functions. Variadic templates will finally allow the creation of true tuple classes in C++.

template<typename T>
void print( const T& t )
{
    std::cout << t;
}

template< typename T, typename... Args>
void print( const T& t, const Args&... args )
{
    print( t );
    print( args... );
}

template<typename... T>
class tuple;
template<typename T, typename... Ts>
class tuple<T,Ts...>;
template<>
class tuple<>;

Variadic templates similar to this exist in D:

real average(T...)(T args) {
    real sum = 0;
    foreach(arg; args) {
        sum += arg;
    }
    return sum / args.length;
}

Variadic functions in C#, VB.net, and Java

Other languages, such as C#, VB.net, and Java use a different approach—they just allow a variable number of arguments of the same (super)type to be passed to a variadic function. Inside the method they are simply collected in an array.

This feature, called "varargs", has been introduced to Java in J2SE 5.0. Using autoboxing, this can also be used to pass primitive arguments to for example a print function, as can be seen in the Java example below:

 public static void printSpaced(Object... objects) {
   for (Object o : objects)
     System.out.print(o + " ");
 }

 // Can be used to print:
 // printSpaced(1, 2, "three");

C# Example:

public static void PrintSpaced(params Object[] objects)
{
    foreach (Object o in objects)
        Console.Write(o + " ");
}

 // Can be used to print:
 // PrintSpaced(1, 2, "three");

VB.Net example:

Public Shared Sub PrintSpaced(ParamArray objects As Object())
    For Each o As Object In objects
        Console.Write(o & " ")
    Next
End Sub

 ' Can be used to print:
 ' PrintSpaced(1, 2, "three")

Variadic functions in Haskell

Haskell's type system can be used to make functions that seem to be able to take an unlimited number of arguments, of different types.

Variadic functions in JavaScript

In JavaScript, the arguments to a function may be accessed as local variables within the function. They also exist as members of a local array within the function, called arguments.

 function printSpaced() {
   for (var i = 0; i < arguments.length; i++) {
     document.write(arguments[i] + " ");
   }
 }

Variadic functions in Perl

In Perl 5, functions don't have an explicit list of parameters (except optional prototypes that are used for limited type checking). All arguments are stored in an array called @_, which can be accessed in the function. Therefore no special effort is needed to accept variable number of arguments.

sub print_spaced {
  my @objects = @_;
  print "@objects\n";
}

sub print_names {
  my ($title, @names) = @_;
  print "This is the list of $title names:\n"
  foreach (@names) {
    print "Name: $_\n";
  }
}

print_spaced(1, 2, "three");

Variadic functions in PHP

In PHP, variable-length argument lists are natively supported (without security risks) since version 4; dedicated functions (func_num_args, func_get_arg, func_get_args) allow the programmer to determine the number and values of unspecified arguments.

function sum() {
    return array_sum(func_get_args());
}

Variadic functions in Python

Python supports very flexible variadic functions. By marking variables with one asterisk (e.g. *var) the given variable is defined to be a tuple of all the extra arguments. By marking variables with two asterisks (e.g. **var) the given variable is a dictionary of all extra keyword arguments; the keys are strings, which are the names that were used to identify the arguments. Conventionally these are called "args" and "kwargs" respectively, but they may be something else, and packages often make good use of this ability to improve readability (e.g. BeautifulSoup). If they exist, these arguments must be the last one in the list.

def f(*args, **kwargs):
    print args
    print kwargs

>>> f(1, 2, "cow", "kitty")
(1, 2, "cow", "kitty")
{}

>>> f(arg1=1, sample=2, name="cow", hero="kitty")
()
{"arg1": 1, "sample": 2, "name": "cow", "hero": "kitty"}

>>> f(1, 2, name="cow", hero="kitty")
(1, 2)
{"name": "cow", "hero": "kitty"}

>>> f(arg1=1, sample=2, name="cow", "kitty")
SyntaxError "Non-keyword arg after keyword arg"

Conversely you may also pass in a tuple or dictionary using the same asterisk-notation and have it automatically expand to fill.

def g(a, b, c):
    print a, b, c

>>> mytuple = 1,2,3
>>> mydict = {"a": "first", "b": "second", "c": "third"}
>>> g(*mytuple)
1 2 3
>>> g(**mydict)
first second third
>>> g(**{"a": "first"})
TypeError "g() takes exactly 3 non-keyword arguments (got 1)"
>>> g(**{"a": "first", "b": "second", "c": "third", "d": "fourth"})
TypeError "g() got an unexpected keyword argument 'd'"

Variadic functions in S-Lang

S-Lang supports two mechanisms for passing optional arguments to a function. The two mechanisms are illustrated by the readascii function that is distributed as part of the S-Lang library. The function is used to read one or more data columns from an ascii (as opposed to binary) file:

readascii ("xy.dat", &x, &y);
readascii ("xydy.dat", &x, &y, &dy);
readascii ("score.dat", &name, &score, &date, &flags;
            format="%s %lf %s %d", skip=5);

The optional keyword/value pairs that follow the semi-colon in the argument list are called qualifiers in S-Lang parlance.

When a function is called, the "_NARGS" variable contains the number of arguments passed to the function. This value does not include the number of qualifiers. Here is a simple example that performs the sum of the arguments (assumed here to be numeric) passed to a function:

define sum_values ()
{
   if (_NARGS == 0)
     usage ("result = sum_values (val1, val2, ...);");
   variable args = __pop_args (_NARGS);
   variable total = 0, arg;
   foreach arg (args) total += arg.value;
   return total;
}
vmessage ("Sum = %g", sum_values (1,2,3,4,5));

Here is a variant of the above that uses a qualifier to alternate between the sum and difference of the successive arguments. This example makes use of the built-in sum function to add the elements of an array.

define sum_values ()
{
   if (_NARGS == 0)
     usage ("result = sum_values (val1, val2, ... ; alternate);");
   variable args = __pop_args (_NARGS);

   % Create an array from the arguments
   variable array = [__push_args(args)];

   % If the sum is to alternate, multiply the odd elements by -1
   if (qualifier_exists ("alternate"))
     array[[1::2]] *= -1;

   return sum(array);
}
vmessage ("Sum = %g", sum_values (1,2,3,4,5 ; alternate));

Variadic functions in Ruby

Ruby supports variadic functions natively. An asterisk before the last parameter in the function declaration declares that parameter to be an array into which all remaining input arguments are placed.

def printNames(listTitle, *nameList)
  puts "This is the list of #{listTitle} names:"
  nameList.each do |name|
    puts "Name: #{name}"
  end
end

printNames("employee", "John", "Bob", "Chris")

#This code produces the following output:
#
#This is the list of employee names:
#Name: John
#Name: Bob
#Name: Chris

Variadic functions in Scheme

In Scheme, there is a dotted notation for representing improper lists (chains of pairs whose last cdr is not null). You can use this notation in argument lists to specify an argument to "dump" the rest of the arguments into.

If a function is defined with the "define" syntax, then you put a dot before the varargs argument

(define (print-spaced . args)
  (for-each
    (lambda (x) (display x) (display " "))
    args))

(define (print-names title . names)
  (display "This is the list of ")
  (display title)
  (display " names:")
  (newline)
  (for-each
    (lambda (x) (display "Name: ") (display x) (newline))
    names))

(print-spaced 1 2 "three")

If a function is defined with the "lambda" syntax, then it is the same thing, except that if there are no arguments before the varargs argument (i.e. if you want to put all the arguments into one thing), then you remove the parentheses altogether; as if to say, let this be the entire argument list.

(define print-spaced
  (lambda args
    (for-each
      (lambda (x) (display x) (display " "))
      args)))

(define print-names
  (lambda (title . names)
    (display "This is the list of ")
    (display title)
    (display " names:")
    (newline)
    (for-each
      (lambda (x) (display "Name: ") (display x) (newline))
      names)))

See also

• Computing
• Java syntax
• Variadic macro (C programming language)
• Variadic Templates

References

External links

• Variable Argument Functions — A tutorial on Variable Argument Functions for C++
• the GNU libc manual