### Section 4.3 Parameters

IF A method IS A BLACK BOX, then a parameter provides a mechanism for passing information from the outside world into the box. Parameters are part of the interface of a method. They allow you to customize the behavior of a method to adapt it to a particular situation.

As an analogy, consider a thermostat -- a black box whose task it is to keep your house at a certain temperature. The thermostat has a parameter, namely the dial that is used to set the desired temperature. The thermostat always performs the same task: maintaining a constant temperature. However, the exact task that it performs -- that is, which temperature it maintains -- is customized by the setting on its dial.

As an example, let's go back to the "3N+1" problem that was discussed in Section 3.2. (Recall that a 3N+1 sequence is computed according to the rule, "if N is odd, multiply by 3 and add 1; if N is even, divide by 2; continue until N is equal to 1." For example, starting from N=3 we get the sequence: 3, 10, 5, 16, 8, 4, 2, 1.) Suppose that we want to write a method to print out such sequences. The method will always perform the same task: Print out a 3N+1 sequence. But the exact sequence it prints out depends on the starting value of N. So, the starting value of N would be a parameter to the method. The method could be written like this:

```         static void Print3NSequence(int startingValue) {

// Prints a 3N+1 sequence to standard output, using
// startingValue as the initial value of N.  It also
// prints the number of terms in the sequence.
// The value of the parameter, startingValue, must
// be a positive integer.

int N;      // One of the terms in the sequence.
int count;  // The number of terms.

N = startingValue;  // The first term is whatever value
//    is passed to the method as
//    a parameter.

int count = 1; // We have one term, the starting value, so far.

TextIO.putln("The 3N+1 sequence starting from " + N);
TextIO.putln();
TextIO.putln(N);  // print initial term of sequence

while (N > 1) {
if (N % 2 == 1)     // is N odd?
N = 3 * N + 1;
else
N = N / 2;
count++;   // count this term
TextIO.putln(N);  // print this term
}

TextIO.putln();
TextIO.putln("There were " + count + " terms in the sequence.");

}  // end of Print3NSequence()
```

The parameter list of this method, "(int startingValue)", specifies that the method has one parameter, of type int. When the method is called, a value must be provided for this parameter. This value is assigned to the parameter, startingValue, before the body of the method is executed. For example, the method could be called using the method call statement "Print3NSequence(17);". When the computer executes this statement, the computer assigns the value 17 to startingValue and then executes the statements in the method. This prints the 3N+1 sequence starting from 17. If K is a variable of type int, then when the computer executes the method call statement "Print3NSequence(K);", it will take the value of the variable K, assign that value to startingValue, and execute the body of the method.

The class that contains Print3NSequence can contain a main() routine (or other methods) that call Print3NSequence. For example, here is a main() program that prints out 3N+1 sequences for various starting values specified by the user:

```         public static void main(String[] args) {
TextIO.putln("This program will print out 3N+1 sequences");
TextIO.putln("for starting values that you specify.");
TextIO.putln();
int K;  // Input from user; loop ends when K < 0.
do {
TextIO.putln("Enter a starting value;")
TextIO.put("To end the program, enter 0: ");
K = TextIO.getInt();  // get starting value from user
if (K > 0)   // print sequence, but only if K is > 0
Print3NSequence(K);
} while (K > 0);   // continue only if K > 0
} // end main()
```

Note that the term "parameter" is used to refer to two different, but related, concepts. There are parameters that are used in the definitions of methods, such as startingValue in the above example. And there are parameters that are used in method call statements, such as the K in the statement "Print3NSequence(K);". Parameters in a method definition are called formal parameters or dummy parameters. The parameters that are passed to a method when it is called are called actual parameters. When a method is called, the actual parameters in the method call statement are evaluated and the values are assigned to the formal parameters in the method's definition. Then the body of the method is executed.

A formal parameter must be an identifier, that is, a name. A formal parameter is very much like a variable, and -- like a variable -- it has a specified type such as int, boolean, or String. An actual parameter is a value, and so it can be specified by any expression, provided that the expression computes a value of the correct type. The type of the actual parameter must be one that could legally be assigned to the formal parameter with an assignment statement. For example, if the formal parameter is of type double, then it would be legal to pass an int as the actual parameter since ints can legally be assigned to doubles. When you call a method, you must provide one actual parameter for each formal parameter in the method's definition. Consider, for example, a method

```         static void doTask(int N, double x, boolean test) {
// statements to perform the task go here
}
```

This method might be called with the statement

When the computer executes this statement, it has essentially the same effect as the block of statements:

```      {
int N;       // Allocate memory locations for the formal parameters.
double x;
boolean test;
N = 17;              // Assign 17 to the first formal parameter, N.
x = Math.sqrt(z+1);  // Compute Math.sqrt(z+1), and assign it to
//    the second formal parameter, x.
test = (z >= 10);    // Evaluate "z >= 10" and assign the resulting
//     true/false value to the third formal
//     parameter, test.
// statements to perform the task go here
}
```

(There are a few technical differences between this and "doTask(17,Math.sqrt(z+1),z>=10);" -- besides the amount of typing -- because of questions about scope of variables and what happens when several variables or parameters have the same name.)

Beginning programming students often find parameters to be surprisingly confusing. Calling a method that already exists is not a problem -- the idea of providing information to the method in a parameter is clear enough. Writing the method definition is another matter. A common mistake is to assign values to the formal parameters at the beginning of the method, or to ask the user to input their values. This represents a fundamental misunderstanding. When the statements in the method are executed, the formal parameters will already have values. The values come from the method call statement. Remember that a method is not independent. It is called by some other routine, and it is the calling routine's responsibility to provide appropriate values for the parameters.

In order to call a method legally, you need to know its name, you need to know how many formal parameters it has, and you need to know the type of each parameter. This information is called the method's signature. The signature of the method doTask can be expressed as as: doTask(int,double,boolean). Note that the signature does not include the names of the parameters; in fact, if you just want to use the method, you don't even need to know what the formal parameter names are, so the names are not part of the interface.

Java is somewhat unusual in that it allows two different methods in the same class to have the same name, provided that their signatures are different. (The language C++ on which Java is based also has this feature.) We say that the name of the method is overloaded because it has several different meanings. The computer doesn't get the methods mixed up. It can tell which one you want to call by the number and types of the actual parameters that you provide in the method call statement. You have already seen overloading used in the TextIO class. This class includes many different methods named putln, for example. These methods all have different signatures, such as:

```      putln(int)       putln(int,int)      putln(double)
putln(String)    putln(String,int)   putln(char)
putln(boolean)   putln(boolean,int)  putln()
```

Of course all these different methods are semantically related, which is why it is acceptable programming style to use the same name for them all. But as far as the computer is concerned, printing out an int is very different from printing out a String, which is different from printing out a boolean, and so forth -- so that each of these operations requires a different method.

Note, by the way, that the signature does not include the method's return type. It is illegal to have two methods in the same class that have the same signature but that have different return types. For example, it would be a syntax error for a class to contain two methods defined as:

```        int    getln() { ... }
double getln() { ... }
```

So it should be no surprise that in the TextIO class, the methods for reading different types are not all named getln(). In a given class, there can only be one routine that has the name getln and has no parameters. The input routines in TextIO are distinguished by having different names, such as getlnInt() and getlnDouble().

Let's do a few examples of writing small methods to perform assigned tasks. Of course, this is only one side of programming with methods. The task performed by a method is always a subtask in a larger program. The art of designing those programs -- of deciding how to break them up into subtasks -- is the other side of programming with methods. We'll return to the question of program design in Section 6.

As a first example, let's write a method to compute and print out all the divisors of a given positive integer. The integer will be a parameter to the method.

Remember that the format of any method is

```      modifiers  return-type  method-name  ( parameter-list ) {
statements
}
```

Writing a method always means filling out this format. The assignment tells us that there is one parameter, of type int, and it tells us what the statements in the body of the method should do. Since we are only working with static methods for now, we'll need to use static as a modifier. We could add an access modifier (public or private), but in the absence of any instructions, I'll leave it out. Since we are not told to return a value, the return type is void. Since no names are specified, we'll have to make up names for the formal parameter and for the method itself. I'll use N for the parameter and printDivisors for the method name. The method will look like

```          static void printDivisors( int N ) {
statements
}
```

and all we have left to do is to write the statements that make up the body of the routine. This is not difficult. Just remember that you have to write the body assuming that N already has a value! The algorithm is: "For each possible divisor D in the range from 1 to N, if D evenly divides N, then print D." Written in Java, this becomes:

```          static void printDivisors( int N ) {
// Print all the divisors of N.
// We assume that N is a positive integer.
int D;   // One of the possible divisors of N.
System.out.println("The divisors of " + N + " are:");
for ( D = 1; D <= N; D++ ) {
if ( N % D == 0 )
System.out.println(D);
}
}
```

I've added comments indicating the contract of the method -- that is, what it does and what assumptions it makes. The contract includes the assumption that N is a positive integer. It is up to the caller of the method to make sure that this assumption is satisfied.

As a second short example, consider the assignment: Write a method named printRow. It should have a parameter ch of type char and a parameter N of type int. The method should print out a line of text containing N copies of the character ch.

Here, we are told the name of the method and the names of the two parameters, so we don't have much choice about the first line of the method definition. The task in this case is pretty simple, so the body of the method is easy to write. The complete method is given by

```        static void printRow( char ch, int N ) {
// Write one line of output containing N copies of the
// character ch.  If N <= 0, an empty line is output.
int i;  // Loop-control variable for counting off the copies.
for ( i = 1; i <= N; i++ ) {
System.out.print( ch );
}
System.out.println();
}
```

Note that in this case, the contract makes no assumption about N, but it makes it clear what will happen in all cases, including the unexpected case that N < 0.

Finally, let's do an example that shows how one method can build on another. Let's write a method that takes a String as a parameter. For each character in the string, it will print a line of output containing 25 copies of that character. It should use the printRow() method to produce the output.

Again, we get to choose a name for the method and a name for the parameter. I'll call the method printRowsFromString and the parameter str. The algorithm is pretty clear: For each position i in the string str, call printRow(str.charAt(i),25) to print one line of the output. So, we get:

```          static void printRowsFromString( String str ) {
// For each character in str, write a line of output
// containing 25 copies of that character.
int i;  // Loop-control variable for counting off the chars.
for ( i = 0; i < str.length(); i++ ) {
printRow( str.charAt(i), 25 );
}
}
```

We could use printRowsFromString in a main() routine such as

```            public static void main(String[] args) {
String inputLine;  // Line of text input by user.
TextIO.put("Enter a line of text: ");
inputLine = TextIO.getln();
TextIO.putln();
printRowsFromString( inputLine );
}
```

Of course, the three routines, main(), printRowsFromString(), and printRow(), would have to be collected together inside the same class.The program is rather useless, but it does demonstrate the use of methods. You'll find the program in the file RowsOfChars.java, if you want to take a look. Here's an applet that simulates the program:

(Applet "RowsOfCharsConsole" would be displayed here
if Java were available.)

I'll finish this section on parameters by noting that we now have three different sorts of variables that can be used inside a method: local variables defined in the method, formal parameter names, and static member variables that are defined outside the method but inside the same class as the method.

Local variables have no connection to the outside world; they are purely part of the internal working of the method. Parameters are used to "drop" values into the method when it is called, but once the method starts executing, parameters act much like local variables. Changes made inside a method to a formal parameter have no effect on the rest of the program (at least if the type of the parameter is one of the primitive types -- things are more complicated in the case of objects, as we'll see later).

Things are different when a method uses a variable that is defined outside the method. That variable exists independently of the method, and it is accessible to other parts of the program, as well as to the method. Such a variable is said to be global to the method, as opposed to the "local" variables defined inside the method. The scope of a global variable includes the entire class in which it is defined. Changes made to a global variable can have effects that extend outside the method where the changes are made. You've seen how this works in the last example in the previous section, where the value of the global variable, gamesWon, is computed inside a method and is used in the main() routine.

It's not always bad to use global variables in methods, but you should realize that the global variable then has to be considered part of the method's interface. The method uses the global variable to communicate with the rest of the program. This is a kind of sneaky, back-door communication that is less visible than communication done through parameters, and it risks violating the rule that the interface of a black box should be straightforward and easy to understand. So before you use a global variable in a method, you should consider whether it's really necessary.

I don't advise you to take an absolute stand against using global variables inside methods. There is at least one good reason to do it: If you think of the class as a whole as being a kind of black box, it can be very reasonable to let the methods inside that box be a little sneaky about communicating with each other, if that will make the class as a whole look simpler from the outside.

[ Next Section | Previous Section | Chapter Index | Main Index ]