Friday, April 15, 2011

Java : Methods with Variable Argument Lists (var-args)

Methods with Variable Argument Lists (var-args)

As of 5.0, Java allows you to create methods that can take a variable number of arguments. Depending on where you look, you might hear this capability referred to as "variable-length argument lists," "variable arguments," "var-args," "varargs, "variable arity parameter". They're all the same thing.

As a bit of background,to use the terms "argument" and "parameter".

arguments The things you specify between the parentheses when you'reinvoking a method:

doStuff("a", 2);   // invoking doStuff, so a & 2 are arguments

parameters The things in the method's signature that indicate what the method must receive when it's invoked:

void doStuff(String s, int a) { } // we're expecting two
                                            // parameters: String and int

The declaration rules for var-args:

Var-arg type When you declare a var-arg parameter, you must specify the type of the argument(s) this parameter of your method can receive. (This can be a primitive type or an object type.)

Basic syntax To declare a method using a var-arg parameter, you follow the type with an ellipsis (...), a space, and then the name of the array that will hold the parameters received.

Other parameters It's legal to have other parameters in a method that uses a var-arg.

Var-args limits The var-arg must be the last parameter in the method's signature, and you can have only one var-arg in a method.

Let's look at some legal and illegal var-arg declarations:

void doStuff(int... x) { }  // expects from 0 to many ints
                                    // as parameters
void doStuff2(char c, int... x) { }  // expects first a char,
                                                 // then 0 to many ints
void doStuff3(Animal... animal) { }  // 0 to many Animals

void doStuff4(int x...) { } // bad syntax
void doStuff5(int... x, char... y) { } // too many var-args
void doStuff6(String... s, byte b) { } // var-arg must be last


As of Java 5, methods can declare a parameter that accepts from zero to many arguments, a so-called var-arg method.

A var-arg parameter is declared with the syntax type... name; 

for instance: 
doStuff(int... x) { }

A var-arg method can have only one var-arg parameter.

In methods with normal parameters and a var-arg, the var-arg must come last.