Arity is a computer science term meaning the number of arguments a method or operator takes. It was originally a joking term, taken from “polarity” meaning the number of poles something has, so by extension “arity” must mean “number of”. Well, just like your mother told you if you pulled a face it would stick like that, the term arity stuck.

In some languages, methods may have variable-arity which means their last or only argument is actually a list of arguments. Congratulations; with JDK 1.5, Java is now one of the languages with variable-arity! This is another hack that was put in Java because some engineers really liked C's printf() function, and wanted Java to have the same convenience.

Luckily, variable-arity (also called var-args by some) has been implemented in a very straightforward way in Java. Here's the code you write to tell the compiler “this is a variable-arity method” in Java:

This declaration actually comes from the API class java.io.PrintWriter. The three dots tell the compiler “args is a sequence of Objects”, so this is a variable-arity method. Inside the body of format(), the args parameter is regarded as type “array of Object”, i.e. it is exactly as though the method were declared:

Where you see a difference is in calls to variable-arity methods. If the last parameter is declared with those three dots known as an ellipsis, then you can call the method with a variable number of objects as that last parameter. They will be automatically assembled into an array for you.

So you can make a call like this:

Primitive variables will even get autoboxed for you.

It doesn't buy all that much. It saves you having to create the array by hand:

Where variable-arity shines is in formatting text. That first argument is a string that can contain ordinary text, and special format specifiers. The ordinary text is carried through literally, and the format specifiers are applied to modify the appearance of the remaining parameters before adding them to the text. The sort of thing you can do is round numbers, specify how many digits should appear, and how many characters wide they should be in all.

The format specifiers are very powerful, very involved, and really make up a special-purpose (rather ugly) programming language of their own. And they work on more than just numbers. There are format specifiers for everything you might want to print: dates, times, text messages, and so on. We'll look at format specifiers in Chapter 17. But you may now write

and get a result like

You can call the same method with a different number of arguments:

to get the result:

There's potential for some confusion with variable-arity methods. When you look at the call, the number of arguments no longer matches the number of parameters. You should try to restrict your use of variable-arity to the purpose intended when it was brought into Java: text string formatting and printing.