csharp Methods

In previous lessons of this tutorial, all of our functionality for each program resided in the Main() method. While this was adequate for the simple programs we used to learn earlier concepts, there is a better way to organize your program, using methods. A method helps you separate your code into modules that perform a given task. The objectives of this lesson are as follows:

• Understand the structure of a method.
• Know the difference between static and instance methods.
• Learn to instantiate objects.
• Learn how to call methods of an instantiated object.
• Understand the 4 types of parameters.
• Learn how to use the this reference.

Method Structure

Methods are extremely useful because they allow you to separate your logic into different units. You can pass information to methods, have it perform one or more statements, and retrieve a return value. The capability to pass parameters and return values is optional and depends on what you want the method to do. Here's a description of the syntax required for creating a method:

    attributes modifiers return-type method-name(parameters )

        {

        statements

        }

We defer discussion of attributes and modifiers to a later lesson. The return-type can be any C# type. It can be assigned to a variable for use later in the program. The method name is a unique identifier for what you wish to call a method. To promote understanding of your code, a method name should be meaningful and associated with the task the method performs. Parameters allow you to pass information to and from a method. They are surrounded by parenthesis. Statements within the curly braces carry out the functionality of the method.

Listing 5-1. One Simple Method: OneMethod.cs

using System;

class OneMethod
{
    public static void Main()
    {
        string myChoice;

        OneMethod om = new OneMethod();

        do
       {
            myChoice = om.getChoice();

            // Make a decision based on the user's choice
            switch(myChoice)
            {
                case "A":
                case "a":
                    Console.WriteLine("You wish to add an address.");
                    break;
                case "D":
                case "d":
                    Console.WriteLine("You wish to delete an address.");
                    break;
                case "M":
                case "m":
                    Console.WriteLine("You wish to modify an address.");
                    break;
                case "V":
                case "v":
                    Console.WriteLine("You wish to view the address list.");
                    break;
                case "Q":
                case "q":
                    Console.WriteLine("Bye.");
                    break;
                default:
                    Console.WriteLine("{0} is not a valid choice", myChoice);
                    break;
            }

            // Pause to allow the user to see the results
            Console.WriteLine();
            Console.Write("press Enter key to continue...");

            Console.ReadLine();
            Console.WriteLine();

        } while (myChoice != "Q" && myChoice != "q"); // Keep going until the user wants to quit
    }

    string getChoice()
    {
        string myChoice;

        // Print A Menu
        Console.WriteLine("My Address Book\n");

        Console.WriteLine("A - Add New Address");
        Console.WriteLine("D - Delete Address");
        Console.WriteLine("M - Modify Address");
        Console.WriteLine("V - View Addresses");
        Console.WriteLine("Q - Quit\n");

        Console.Write("Choice (A,D,M,V,or Q): ");

        // Retrieve the user's choice
        myChoice = Console.ReadLine();
        Console.WriteLine();

        return myChoice;
    }
}

The program in Listing 5-1 is similar to the DoLoop program from Lesson 4, except for one difference. Instead of printing the menu and accepting input in the Main() method, this functionality has been moved to a new method called getChoice(). The return type is a string. This string is used in the switch statement in Main(). The method name "getChoice" describes what happens when it is invoked. Since the parentheses are empty, no information will be transferred to the getChoice() method.

Within the method block we first declare the variable myChoice. Although this is the same name and type as the myChoice variable in Main(), they are both unique variables. They are local variables and they are visible only in the block they are declared. In other words, the myChoice in getChoice() knows nothing about the existence of the myChoice in Main(), and vice versa.

The getChoice() method prints a menu to the console and gets the user's input. The return statement sends the data from the myChoice variable back to the caller, Main(), of getChoice(). Notice that the type returned by the return statement must be the same as the return-type in the function declaration. In this case it is a string.

In the Main() method we must instantiate a new OneMethod object before we can use getChoice(). This is because of the way getChoice() is declared. Since we did not specify a static modifier, as for Main(), getChoice() becomes an instance method. The difference between instance methods and static methods is that multiple instances of a class can be created (or instantiated) and each instance has its own separate getChoice() method. However, when a method is static, there are no instances of that method, and you can invoke only that one definition of the static method.

So, as stated, getChoice() is not static and therefore, we must instantiate a new object to use it. This is done with the declaration OneMethod om = new OneMethod(). On the left hand side of the declaration is the object reference om which is of type OneMethod. T

he distinction of om being a reference is important. It is not an object itself, but it is a variable that can refer (or point ) to an object of type OneMethod. On the right hand side of the declaration is an assignment of a new OneMethod object to the reference om. The keyword new is a C# operator that creates a new instance of an object on the heap. What is happening here is that a new OneMethod instance is being created on the heap and then being assigned to the om reference. Now that we have an instance of the OneMethod class referenced by om, we can manipulate that instance through the om reference.

Methods, fields, and other class members can be accessed, identified, or manipulated through the "." (dot) operator. Since we want to call getChoice(), we do so by using the dot operator through the om reference: om.getChoice().

The program then executes the statements in the getChoice() block and returns. To capture the value getChoice() returns, we use the "=" (assignment) operator. The returned string is placed into Main()'s local myChoice variable. From there, the rest of the program executes as expected, using concepts from earlier lessons.

Listing 5-2. Method Parameters: MethodParams.cs

using System;

class Address
{
    public string name;
    public string address;
}

class MethodParams
{
    public static void Main()
    {
        string myChoice;

        MethodParams mp = new MethodParams();

        do
       {
            // show menu and get input from user
            myChoice = mp.getChoice();

            // Make a decision based on the user's choice
            mp.makeDecision(myChoice);

            // Pause to allow the user to see the results
            Console.Write("press Enter key to continue...");
            Console.ReadLine();
            Console.WriteLine();
        } while (myChoice != "Q" && myChoice != "q"); // Keep going until the user wants to quit
    }

    // show menu and get user's choice
    string getChoice()
    {
        string myChoice;

        // Print A Menu
        Console.WriteLine("My Address Book\n");

        Console.WriteLine("A - Add New Address");
        Console.WriteLine("D - Delete Address");
        Console.WriteLine("M - Modify Address");
        Console.WriteLine("V - View Addresses");
        Console.WriteLine("Q - Quit\n");

        Console.WriteLine("Choice (A,D,M,V,or Q): ");

        // Retrieve the user's choice
        myChoice = Console.ReadLine();

        return myChoice;
    }

    // make decision
    void makeDecision(string myChoice)
    {
        Address addr = new Address();

        switch(myChoice)
        {
            case "A":
            case "a":
                addr.name = "Joe";
                addr.address = "C# Station";
                this.addAddress(ref addr);
                break;
            case "D":
            case "d":
                addr.name = "Robert";
                this.deleteAddress(addr.name);
                break;
            case "M":
            case "m":
                addr.name = "Matt";
                this.modifyAddress(out addr);
                Console.WriteLine("Name is now {0}.", addr.name);
                break;
            case "V":
            case "v":
                this.viewAddresses("Cheryl", "Joe", "Matt", "Robert");
                break;
            case "Q":
            case "q":
                Console.WriteLine("Bye.");
                break;
            default:
                Console.WriteLine("{0} is not a valid choice", myChoice);
                break;
        }
    }

    // insert an address
    void addAddress(ref Address addr)
    {
        Console.WriteLine("Name: {0}, Address: {1} added.", addr.name, addr.address);
    }

    // remove an address
    void deleteAddress(string name)
    {
        Console.WriteLine("You wish to delete {0}'s address.", name);
    }

    // change an address
    void modifyAddress(out Address addr)
    {
        //Console.WriteLine("Name: {0}.", addr.name); // causes error!
        addr = new Address();
        addr.name = "Joe";
        addr.address = "C# Station";
    }

    // show addresses
    void viewAddresses(params string[] names)
    {
        foreach (string name in names)
        {
            Console.WriteLine("Name: {0}", name);
        }
    }
}

Listing 5-2 is a modification of Listing 5-1, modularizing the program and adding more implementation to show parameter passing. There are 4 kinds of parameters a C# method can handle: out, ref, params, and value. To help illustrate usage of parameters, we created an Address class with two string fields.

In Main() we call getChoice() to get the user's input and put that string in the myChoice variable. Then we use myChoice as an argument to makeDecision(). In the declaration of makeDecision() you'll notice its one parameter is declared as a string with the name myChoice.

 Again, this is a new myChoice, separate from the caller's argument and local only to this method. Since makeDecision()'s myChoice parameter does not have any other modifiers, it is considered a value parameter. The actual value of the argument is copied on the stack. Variables given by value parameters are local and any changes to that local variable do not affect the value of the variable used in the caller's argument.

The switch statement in makeDecision() calls a method for each case. These method calls are different from the ones we used in Main(). Instead of using the mp reference, they use the this keyword. this is a reference to the current object. We know the current object has been instantiated because makeDecision() is not a static method. Therefore, we can use the this reference to call methods within the same instance.

The addAddress() method takes a ref parameter. This means that a reference to the parameter is copied to the method. This reference still refers to the same object on the heap as the original reference used in the caller's argument. This means any changes to the local reference's object also changes the caller reference's object. The code can't change the reference, but it can make changes to the object being referenced. You can think of this as a way to have an input/output parameter.

As you know, methods have return values, but sometimes you'll want to return more than one value from a method. An out parameter allows you to return additional values from a method.

modifyAddress() has an out parameter. out parameters are only passed back to the calling function. Because of definite assignment rules, you cannot use this variable until it has a valid value assigned. The first line in modifyAddress() is commented on purpose to illustrate this point.

Uncomment it and compile to see what happens. Once assigned and the program returns, the value of the out parameter will be copied into the caller's argument variable. You must assign a value to an out parameter before your method returns.

A very useful addition to the C# language is the params parameter, which lets you define a method that can accept a variable number of arguments. The params parameter must be a single dimension or jagged array. When calling viewAddresses(), we pass in four string arguments.

The number of arguments is variable and will be converted to a string[] automatically. In viewAddresses() we use a foreach loop to print each of these strings. Instead of the list of string arguments, the input could have also been a string array. The params parameter is considered an input only parameter and any changes affect the local copy only.

In summary, you understand the structure of a method. The four types of paramters are value, ref, out, and params. When you wish to use an instance method, you must instantiate its object as opposed to static methods that can be called any time. The this reference refers to its containing object and may be used to refer to its containing object's members, including methods.

, all of our functionality for each program resided in the Main() method. While this was adequate for the simple programs we used to learn earlier concepts, there is a better way to organize your program, using methods. A method helps you separate your code into modules that perform a given task. The objectives of this lesson are as follows:

• Understand the structure of a method.
• Know the difference between static and instance methods.
• Learn to instantiate objects.
• Learn how to call methods of an instantiated object.
• Understand the 4 types of parameters.
• Learn how to use the this reference.

Method Structure.

Methods are extremely useful because they allow you to separate your logic into different units. You can pass information to methods, have it perform one or more statements, and retrieve a return value. The capability to pass parameters and return values is optional and depends on what you want the method to do. Here's a description of the syntax required for creating a method:

    attributes modifiers return-type method-name(parameters )

        {

        statements

        }

We defer discussion of attributes and modifiers to a later lesson. The return-type can be any C# type. It can be assigned to a variable for use later in the program. The method name is a unique identifier for what you wish to call a method. To promote understanding of your code, a method name should be meaningful and associated with the task the method performs. Parameters allow you to pass information to and from a method. They are surrounded by parenthesis. Statements within the curly braces carry out the functionality of the method.

Listing 5-1. One Simple Method: OneMethod.cs

using System;

class OneMethod
{
    public static void Main()
    {
        string myChoice;

        OneMethod om = new OneMethod();

        do
       {
            myChoice = om.getChoice();

            // Make a decision based on the user's choice
            switch(myChoice)
            {
                case "A":
                case "a":
                    Console.WriteLine("You wish to add an address.");
                    break;
                case "D":
                case "d":
                    Console.WriteLine("You wish to delete an address.");
                    break;
                case "M":
                case "m":
                    Console.WriteLine("You wish to modify an address.");
                    break;
                case "V":
                case "v":
                    Console.WriteLine("You wish to view the address list.");
                    break;
                case "Q":
                case "q":
                    Console.WriteLine("Bye.");
                    break;
                default:
                    Console.WriteLine("{0} is not a valid choice", myChoice);
                    break;
            }

            // Pause to allow the user to see the results
            Console.WriteLine();
            Console.Write("press Enter key to continue...");

            Console.ReadLine();
            Console.WriteLine();

        } while (myChoice != "Q" && myChoice != "q"); // Keep going until the user wants to quit
    }

    string getChoice()
    {
        string myChoice;

        // Print A Menu
        Console.WriteLine("My Address Book\n");

        Console.WriteLine("A - Add New Address");
        Console.WriteLine("D - Delete Address");
        Console.WriteLine("M - Modify Address");
        Console.WriteLine("V - View Addresses");
        Console.WriteLine("Q - Quit\n");

        Console.Write("Choice (A,D,M,V,or Q): ");

        // Retrieve the user's choice
        myChoice = Console.ReadLine();
        Console.WriteLine();

        return myChoice;
    }
}

The program in Listing 5-1 is similar to the DoLoop program from Lesson 4, except for one difference. Instead of printing the menu and accepting input in the Main() method, this functionality has been moved to a new method called getChoice(). The return type is a string. This string is used in the switch statement in Main(). The method name "getChoice" describes what happens when it is invoked. Since the parentheses are empty, no information will be transferred to the getChoice() method.

Within the method block we first declare the variable myChoice. Although this is the same name and type as the myChoice variable in Main(), they are both unique variables. They are local variables and they are visible only in the block they are declared. In other words, the myChoice in getChoice() knows nothing about the existence of the myChoice in Main(), and vice versa.

The getChoice() method prints a menu to the console and gets the user's input. The return statement sends the data from the myChoice variable back to the caller, Main(), of getChoice(). Notice that the type returned by the return statement must be the same as the return-type in the function declaration. In this case it is a string.

In the Main() method we must instantiate a new OneMethod object before we can use getChoice(). This is because of the way getChoice() is declared. Since we did not specify a static modifier, as for Main(), getChoice() becomes an instance method. The difference between instance methods and static methods is that multiple instances of a class can be created (or instantiated) and each instance has its own separate getChoice() method. However, when a method is static, there are no instances of that method, and you can invoke only that one definition of the static method.

So, as stated, getChoice() is not static and therefore, we must instantiate a new object to use it. This is done with the declaration OneMethod om = new OneMethod(). On the left hand side of the declaration is the object reference om which is of type OneMethod. The distinction of om being a reference is important. It is not an object itself, but it is a variable that can refer (or point ) to an object of type OneMethod. On the right hand side of the declaration is an assignment of a new OneMethod object to the reference om.

The keyword new is a C# operator that creates a new instance of an object on the heap. What is happening here is that a new OneMethod instance is being created on the heap and then being assigned to the om reference. Now that we have an instance of the OneMethod class referenced by om, we can manipulate that instance through the om reference.

Methods, fields, and other class members can be accessed, identified, or manipulated through the "." (dot) operator. Since we want to call getChoice(), we do so by using the dot operator through the om reference: om.getChoice(). The program then executes the statements in the getChoice() block and returns. To capture the value getChoice() returns, we use the "=" (assignment) operator. The returned string is placed into Main()'s local myChoice variable. From there, the rest of the program executes as expected, using concepts from earlier lessons.

Listing 5-2. Method Parameters: MethodParams.cs

using System;

class Address
{
    public string name;
    public string address;
}

class MethodParams
{
    public static void Main()
    {
        string myChoice;

        MethodParams mp = new MethodParams();

        do
       {
            // show menu and get input from user
            myChoice = mp.getChoice();

            // Make a decision based on the user's choice
            mp.makeDecision(myChoice);

            // Pause to allow the user to see the results
            Console.Write("press Enter key to continue...");
            Console.ReadLine();
            Console.WriteLine();
        } while (myChoice != "Q" && myChoice != "q"); // Keep going until the user wants to quit
    }

    // show menu and get user's choice
    string getChoice()
    {
        string myChoice;

        // Print A Menu
        Console.WriteLine("My Address Book\n");

        Console.WriteLine("A - Add New Address");
        Console.WriteLine("D - Delete Address");
        Console.WriteLine("M - Modify Address");
        Console.WriteLine("V - View Addresses");
        Console.WriteLine("Q - Quit\n");

        Console.WriteLine("Choice (A,D,M,V,or Q): ");

        // Retrieve the user's choice
        myChoice = Console.ReadLine();

        return myChoice;
    }

    // make decision
    void makeDecision(string myChoice)
    {
        Address addr = new Address();

        switch(myChoice)
        {
            case "A":
            case "a":
                addr.name = "Joe";
                addr.address = "C# Station";
                this.addAddress(ref addr);
                break;
            case "D":
            case "d":
                addr.name = "Robert";
                this.deleteAddress(addr.name);
                break;
            case "M":
            case "m":
                addr.name = "Matt";
                this.modifyAddress(out addr);
                Console.WriteLine("Name is now {0}.", addr.name);
                break;
            case "V":
            case "v":
                this.viewAddresses("Cheryl", "Joe", "Matt", "Robert");
                break;
            case "Q":
            case "q":
                Console.WriteLine("Bye.");
                break;
            default:
                Console.WriteLine("{0} is not a valid choice", myChoice);
                break;
        }
    }

    // insert an address
    void addAddress(ref Address addr)
    {
        Console.WriteLine("Name: {0}, Address: {1} added.", addr.name, addr.address);
    }

    // remove an address
    void deleteAddress(string name)
    {
        Console.WriteLine("You wish to delete {0}'s address.", name);
    }

    // change an address
    void modifyAddress(out Address addr)
    {
        //Console.WriteLine("Name: {0}.", addr.name); // causes error!
        addr = new Address();
        addr.name = "Joe";
        addr.address = "C# Station";
    }

    // show addresses
    void viewAddresses(params string[] names)
    {
        foreach (string name in names)
        {
            Console.WriteLine("Name: {0}", name);
        }
    }
}

Listing 5-2 is a modification of Listing 5-1, modularizing the program and adding more implementation to show parameter passing. There are 4 kinds of parameters a C# method can handle: out, ref, params, and value. To help illustrate usage of parameters, we created an Address class with two string fields.

In Main() we call getChoice() to get the user's input and put that string in the myChoice variable. Then we use myChoice as an argument to makeDecision(). In the declaration of makeDecision() you'll notice its one parameter is declared as a string with the name myChoice. Again,
 this is a new myChoice, separate from the caller's argument and local only to this method. Since makeDecision()'s myChoice parameter does not have any other modifiers, it is considered a value parameter.

The actual value of the argument is copied on the stack. Variables given by value parameters are local and any changes to that local variable do not affect the value of the variable used in the caller's argument.

The switch statement in makeDecision() calls a method for each case. These method calls are different from the ones we used in Main(). Instead of using the mp reference, they use the this keyword. this is a reference to the current object. We know the current object has been instantiated because makeDecision() is not a static method. Therefore, we can use the this reference to call methods within the same instance.

The addAddress() method takes a ref parameter. This means that a reference to the parameter is copied to the method. This reference still refers to the same object on the heap as the original reference used in the caller's argument. This means any changes to the local reference's object also changes the caller reference's object. The code can't change the reference, but it can make changes to the object being referenced. You can think of this as a way to have an input/output parameter.

As you know, methods have return values, but sometimes you'll want to return more than one value from a method. An out parameter allows you to return additional values from a method.

modifyAddress() has an out parameter. out parameters are only passed back to the calling function. Because of definite assignment rules, you cannot use this variable until it has a valid value assigned.

 The first line in modifyAddress() is commented on purpose to illustrate this point. Uncomment it and compile to see what happens. Once assigned and the program returns, the value of the out parameter will be copied into the caller's argument variable. You must assign a value to an out parameter before your method returns.

A very useful addition to the C# language is the params parameter, which lets you define a method that can accept a variable number of arguments. The params parameter must be a single dimension or jagged array. When calling viewAddresses(), we pass in four string arguments. The number of arguments is variable and will be converted to a string[] automatically. In viewAddresses() we use a foreach loop to print each of these strings. Instead of the list of string arguments, the input could have also been a string array. The params parameter is considered an input only parameter and any changes affect the local copy only.

In summary, you understand the structure of a method. The four types of paramters are value, ref, out, and params. When you wish to use an instance method, you must instantiate its object as opposed to static methods that can be called any time. The this reference refers to its containing object and may be used to refer to its containing object's members, including methods.