An access modifier determines which members of your class can be seen and used by methods of other classes. As you saw in the previous section, you also place an access modifier on the class itself, limiting the visibility of the class to methods of other classes. Table 4-1 summarizes the C# access modifiers.

It is generally desirable to designate the member variables of a class as private. This means that only member methods of that class can access their value. Because private is the default accessibility level, you don’t need to make it explicit, but we recommend that you do so. Thus, in Example 4-1, the declarations of member variables should have been written as follows:

// private variables
private int Year;
private int Month;
private int Date;
private int Hour;
private int Minute;
private int Second;

The Tester class and DisplayCurrentTime( ) method are both declared public so that any other class can make use of them.

Methods can take any number of parameters.^[3] The parameter list follows the method name and is enclosed in parentheses, with each parameter preceded by its type. For example, the following declaration defines a method named MyMethod( ), which returns void (that is, which returns no value at all) and which takes two parameters: an integer and a button.

void MyMethod (int firstParam, Button secondParam)
{
  // ...
}

Within the body of the method, the parameters act as local variables, as though you had declared them in the body of the method and initialized them with the values passed in. Example 4-2 illustrates how you pass values into a method—in this case, values of type int and float.

using System;

namespace PassingValues
{
  public class MyClass
  {
    public void SomeMethod( int firstParam, float secondParam )
    {
      Console.WriteLine(
        "Here are the parameters received: {0}, {1}",
        firstParam, secondParam );
    }
  }

  public class Tester
  {
    static void Main(  )
    {
      int howManyPeople = 5;
      float pi = 3.14f;
      MyClass mc = new MyClass(  );
    mc.SomeMethod( howManyPeople, pi );
   }
  }
}

The method SomeMethod( ) takes an int and a float and displays them using Console.WriteLine( ). The parameters, which are named firstParam and secondParam, are treated as local variables within SomeMethod( ).

In the calling method (Main), two local variables (howManyPeople and pi) are created and initialized. These variables are passed as the parameters to SomeMethod( ). The compiler maps howManyPeople to firstParam and pi to secondParam, based on their positions in the parameter list.

In Example 4-1, notice that the statement that creates the Time object looks as though it is invoking a method:

Time t = new Time(  );

In fact, a method is invoked whenever you instantiate an object. This method is called a constructor, and you must either define one as part of your class definition or let the compiler provide one on your behalf. The job of a constructor is to create the object specified by a class and to put it into a valid state. Before the constructor runs, the object is undifferentiated memory; after the constructor completes, the memory holds a valid instance of the class type.

The Time class of Example 4-1 doesn’t define a constructor. Because a constructor is not declared, the compiler provides one for you. The default constructor creates the object but takes no other action.

Member variables are initialized to innocuous values (integers to 0, strings to null, etc.).^[4] Table 4-2 lists the default values assigned to primitive types.

Typically, you’ll want to define your own constructor and provide it with arguments so that the constructor can set the initial state for your object. In Example 4-1, assume that you want to pass in the current year, month, date, and so forth so that the object is created with meaningful data.

To define a constructor, you declare a method whose name is the same as the class in which it is declared. Constructors have no return type and are typically declared public. If there are arguments to pass, you define an argument list just as you would for any other method. Example 4-3 declares a constructor for the Time class that accepts a single argument, an object of type DateTime.

using System;

namespace DeclaringConstructor
{
  public class Time
  {

    // private member variables
    int Year;
    int Month;
    int Date;
    int Hour;
    int Minute;
    int Second;

    // public accessor methods
    public void DisplayCurrentTime(  )
    {
      System.Console.WriteLine( "{0}/{1}/{2} {3}:{4}:{5}",
        Month, Date, Year, Hour, Minute, Second );
    }// constructor
    public Time( System.DateTime dt )
   {

      Year = dt.Year;

      Month = dt.Month;
      Date = dt.Day;
      Hour = dt.Hour;
      Minute = dt.Minute;
      Second = dt.Second;
    }
  }

  public class Tester
  {
    static void Main(  )
    {
      System.DateTime currentTime = System.DateTime.Now;
      Time t = new Time( currentTime );
      t.DisplayCurrentTime(  );
    }
  }
}

Output:
11/16/2007 16:21:40

In this example, the constructor takes a DateTime object and initializes all the member variables based on values in that object. When the constructor finishes, the Time object exists and the values have been initialized. When DisplayCurrentTime( ) is called in Main( ), the values are displayed.

Try commenting out one of the assignments and running the program again. You’ll find that the member variable is initialized by the compiler to 0. Integer member variables are set to 0 if you don’t otherwise assign them. Remember, value types (e.g., integers) can’t be uninitialized; if you don’t tell the constructor what to do, it will set the value types to their default values.

In Example 4-3, the DateTime object is created in the Main( ) method of Tester. This object, supplied by the System library, offers a number of public values—Year, Month, Day, Hour, Minute, and Second—that correspond directly to the private member variables of the Time object. In addition, the DateTime object offers a static member property, Now, which is a reference to an instance of a DateTime object initialized with the current time.

Examine the highlighted line in Main( ), where the DateTime object is created by calling the static property Now. Now creates a DateTime value which, in this case, gets copied to the currentTime variable on the stack.

The currentTime variable is passed as a parameter to the Time constructor. The Time constructor parameter, dt, is a copy of the DateTime object.

It is possible to initialize the values of member variables in an initializer, instead of having to do so in the constructor. You create an initializer by assigning an initial value to a class member:

private int Second = 30; // initializer

Assume that the semantics of the Time object are such that no matter what time is set, the seconds are always initialized to 30. You might rewrite the Time class to use an initializer so that no matter which constructor is called, the value of Second is always initialized, either explicitly by the constructor, or implicitly by the initializer. See Example 4-4.

using System;

namespace Initializer
{
  public class Time
  {
    // private member variables
    private int Year;
    private int Month;
    private int Date;
    private int Hour;
    private int Minute;
    private int Second = 30; // initializer

    // public accessor methods
    public void DisplayCurrentTime(  )
    {
      System.DateTime now = System.DateTime.Now;
      System.Console.WriteLine(
        "
Debug	: {0}/{1}/{2} {3}:{4}:{5}",
        now.Month, now.Day, now.Year, now.Hour,
        now.Minute, now.Second );

      System.Console.WriteLine( "Time	: {0}/{1}/{2} {3}:{4}:{5}",
        Month, Date, Year, Hour, Minute, Second );
    }

    // constructorspublic Time( System.DateTime dt )
    {
      Year = dt.Year;
      Month = dt.Month;
      Date = dt.Day;
      Hour = dt.Hour;
      Minute = dt.Minute;
      Second = dt.Second; //explicit assignment
    }

    public Time( int Year, int Month, int Date, int Hour, int Minute )
    {
      this.Year = Year;
      this.Month = Month;
      this.Date = Date;
      this.Hour = Hour;
      this.Minute = Minute;
    }
  }

  public class Tester
  {
    static void Main(  )
    {
      System.DateTime currentTime = System.DateTime.Now;
      Time t = new Time( currentTime );
      t.DisplayCurrentTime(  );

      Time t2 = new Time( 2007, 11, 18, 11, 45 );
      t2.DisplayCurrentTime(  );
    }
  }
}

Output:
Debug : 11/27/2007 7:52:54
Time : 11/27/2007 7:52:54

Debug : 11/27/2007 7:52:54
Time : 11/18/2007 11:45:30

If you don’t provide a specific initializer, the constructor will initialize each integer member variable to zero (0). In the case shown, however, the Second member is initialized to 30:

private int Second = 30; // initializer

If a value is not passed in for Second, its value will be set to 30 when t2 is created:

Time t2 = new Time(2007,11,18,11,45);
t2.DisplayCurrentTime(  );

However, if a value is assigned to Second, as is done in the constructor (which takes a DateTime object, shown in bold), that value overrides the initialized value.

The first time we invoke DisplayCurrentTime( ), we call the constructor that takes a DateTime object, and the seconds are initialized to 54. The second time the method is invoked, we explicitly set the time to 11:45 (not setting the seconds), and the initializer takes over.

If the program didn’t have an initializer and did not otherwise assign a value to Second, the value would be initialized by the CLR to 0.

An alternative to calling the constructor to initialize the private member values of the Time class is to use a new feature in C# 3.0 called the object initializer, which allows you to initialize objects without invoking a constructor explicitly. In fact, you need not even define a constructor that initializes the object properties. All you need to do is to specify the value of each public property in the object initializer as shown in Example 4-5.

using System;

namespace ObjectInitializer
{
    public class Time
    {
        // private member variables
        public int Year;
        public int Month;
        public int Date;
        public int Hour;
        public int Minute;
        public int Second = 30; // initializer

        public void DisplayCurrentTime(  )
        {
            System.Console.WriteLine("Time	: {0}/{1}/{2} {3}:{4}:{5}",
              Month, Date, Year, Hour, Minute, Second);
        }

    }

    public class Tester
    {
        static void Main(  )
        {
            Time t = new Time {
              Year = 2009, Month = 7, Date = 10, Hour = 11, Minute = 15 };
            t.DisplayCurrentTime(  );
        }
    }
}

Output:
Time    : 7/10/2009 11:15:30

The following object initialization:

Time t = new Time {
  Year = 2009, Month = 7, Date = 10, Hour = 11, Minute = 15 };

Is the equivalent of creating the object and then assigning values to its public members:

Time t = new Time(  );
t.Year = 200;
t.Month = 7;
t.Date = 10;
t.Hour = 11;
t.Minute = 15;

The keyword this refers to the current instance of an object. The this reference (sometimes referred to as a this pointer^[5]) is a hidden reference passed to every nonstatic method of a class. Each method can refer to the other methods and variables of its own object by way of the this reference.

The this reference is used in a number of ways. The first way is to qualify instance members otherwise hidden by parameters, as in the following:

public void SomeMethod (int hour)
{
  this.hour = hour;
}

In this example, SomeMethod( ) takes a parameter (hour) with the same name as a member variable of the class. The this reference is used to resolve the name ambiguity. Whereas this.hour refers to the member variable, hour refers to the parameter.

The argument in favor of this style is that you pick the right variable name and then use it for the parameter and the member variable. The counter argument is that using the same name for the parameter and the member variable can be confusing.

The second use of the this reference is to pass the current object as a parameter to another method. For instance:

class myClass
{
  public void Foo(OtherClass otherObject)
  {
    otherObject.Bar(this);
  }
}

Let’s unpack this example. Here, we have a method named myClass.Foo. In the body of this method, you invoke the Bar method of the OtherClass instance, passing in a reference to the current instance of myClass. This allows the Bar method to fiddle with the public methods and members of the current instance of myClass.

The third use of this is with indexers, covered in Chapter 9.

The fourth use of the this reference is to call one overloaded constructor from another, for example:

class myClass
{
  public myClass(int i) { //... }
  public myClass(  ) : this(42) { //... }
}

In this example, the default constructor invokes the overloaded constructor that takes an integer, by using the this keyword.

The final way that the this keyword is used is to explicitly invoke methods and members of a class as a form of documentation:

public void MyMethod(int y)
{
  int x = 0;
  x = 7; // assign to a local variable
  y = 8; // assign to a parameter
  this.z = 5; // assign to a member variable
  this.Draw(  ); // invoke member method
}

In the cases shown, the use of the this reference is superfluous, but may make the programmer’s intent clearer and does no harm (except, arguably, to clutter the code).

The Main( ) method is static. Static methods are said to operate on the class, rather than on an instance of the class. They don’t have a this reference, as there is no instance to point to.

Static methods can’t directly access nonstatic members. For Main( ) to call a nonstatic method, it must instantiate an object. Consider Example 4-2, which was shown earlier.

SomeMethod( ) is a nonstatic method of MyClass. For Main( ) to access this method, it must first instantiate an object of type MyClass and then invoke the method through that object.

A common way to demonstrate the use of static member variables is to keep track of the number of instances that currently exist for your class. Example 4-6 illustrates.

using System;

namespace StaticFields
{
  public class Cat
  {

    private static int instances = 0;

    public Cat(  )
    {
      instances++;
    }

    public static void HowManyCats(  )
    {
      Console.WriteLine( "{0} cats adopted", instances );
    }
  }

  public class Tester
  {
    static void Main(  )
    {
      Cat.HowManyCats(  );
      Cat frisky = new Cat(  );
      Cat.HowManyCats(  );
      Cat whiskers = new Cat(  );
      Cat.HowManyCats(  );
    }
  }
}

Output:
0 cats adopted
1 cats adopted
2 cats adopted

The Cat class has been stripped to its absolute essentials. A static member variable called instances is created and initialized to 0. Note that the static member is considered part of the class, not a member of an instance, and so it can’t be initialized by the compiler on creation of an instance. Thus, if you want to initialize a static member, you must provide an explicit initializer. When additional instances of Cats are created (in a constructor), the count is incremented.

It is not legal to call a finalizer explicitly. Your finalizer will be called by the garbage collector. If you do handle precious unmanaged resources (such as file handles) that you want to close and dispose of as quickly as possible, you ought to implement the IDisposable interface.^[7] (You will learn more about interfaces in Chapter 8.) The IDisposable interface requires its implementers to define one method, named Dispose( ), to perform whatever cleanup you consider to be crucial. The availability of Dispose( ) is a way for your clients to say, “Don’t wait for the finalizer to be called, do it right now.”

If you provide a Dispose( ) method, you should stop the garbage collector from calling your object’s finalizer. To do so, call the static method GC.SuppressFinalize( ), passing in the this pointer for your object. Your finalizer can then call your Dispose( ) method. Thus, you might write:

using System;
class Testing : IDisposable
{
  bool is_disposed = false;
  protected virtual void Dispose(bool disposing)
  {
    if (!is_disposed) // only dispose once!
    {
      if (disposing)
      {
        Console.WriteLine(
        "Not in finalizer, OK to reference other objects");
      }
      // perform cleanup for this object
      Console.WriteLine("Disposing...");
    }
    this.is_disposed = true;
  }

  public void Dispose(  )
  {
    Dispose(true);
    // tell the GC not to finalize
    GC.SuppressFinalize(this);
  }

  ~Testing(  )
  {
    Dispose(false);
    Console.WriteLine("In finalizer.");
  }
}

For some objects, you may prefer to have your clients call a method named Close( ). (For example, Close( ) may make more sense than Dispose( ) for file objects.) You can implement this by creating a private Dispose( ) method and a public Close( ) method, and having your Close( ) method invoke Dispose( ).

To make it easier for your clients to properly dispose of your objects, C# provides a using statement that ensures that Dispose( ) will be called at the earliest possible time. The idiom is to declare the objects you are using and then to create a scope for these objects with curly braces. When the closing brace is reached, the Dispose( ) method will be called on the object automatically, as illustrated in Example 4-7.

using System.Drawing;

namespace usingStatement
{
  class Tester
  {
    public static void Main(  )
    {
      using ( Font theFont = new Font( "Arial", 10.0f ) )
      {
        // use theFont
      } // compiler will call Dispose on theFont

      Font anotherFont = new Font( "Courier", 12.0f );

      using ( anotherFont )
      {
        // use anotherFont
      } // compiler calls Dispose on anotherFont
    }
  }
}

In the first part of this example, the Font object is created within the using statement. When the using statement ends, Dispose( ) is called on the Font object.

In the second part of the example, a Font object is created outside the using statement. When we decide to use that font, we put it inside the using statement; when that statement ends, Dispose( ) is called once again.

This second approach is fraught with danger. If an exception is thrown after the object is created, but before the using block is begun, the object will not be disposed. Second, the variable remains in scope after the using block ends, but if it is accessed, it will fail.

The using statement also protects you against unanticipated exceptions. Regardless of how control leaves the using statement (including you placing a return statement in the middle of the block), Dispose( ) is called. An implicit try-finally block is created for you. (See Chapter 11 for details.)

Methods can return only a single value (though that value can itself be a collection of values). Let’s return to the Time class and add a GetTime( ) method, which returns the hour, minutes, and seconds.

Because you can’t return three values, perhaps you can pass in three parameters, let the method modify the parameters, and examine the result in the calling method. Example 4-8 shows a first attempt at this.

using System;

namespace ReturningValuesInParams
{
  public class Time
  {
    // private member variables
    private int Year;
    private int Month;
    private int Date;
    private int Hour;
    private int Minute;
    private int Second;

    // public accessor methods
    public void DisplayCurrentTime(  )
    {
       System.Console.WriteLine( "{0}/{1}/{2} {3}:{4}:{5}",
         Month, Date, Year, Hour, Minute, Second );
    }

    public int GetHour(  )
    {
      return Hour;
    }

    public void GetTime( int h, int m, int s )
    {
      h = Hour;
      m = Minute;
      s = Second;
    }

    // constructor
    public Time( System.DateTime dt )
    {

      Year = dt.Year;
      Month = dt.Month;
      Date = dt.Day;
      Hour = dt.Hour;
      Minute = dt.Minute;
      Second = dt.Second;
    }
  }

  public class Tester
  {
    static void Main(  )
    {
      System.DateTime currentTime = System.DateTime.Now;
      Time t = new Time( currentTime );
      t.DisplayCurrentTime(  );

      int theHour = 0;
      int theMinute = 0;
      int theSecond = 0;
      t.GetTime( theHour, theMinute, theSecond );
      System.Console.WriteLine( "Current time: {0}:{1}:{2}",
        theHour, theMinute, theSecond );
    }
  }
}

Output:
11/17/2007 13:41:18
Current time: 0:0:0

Notice that the Current time in the output is 0:0:0. Clearly, this first attempt did not work. The problem is with the parameters. You pass in three integer parameters to GetTime( ), where they are modified, but when the values are accessed back in Main( ), they are unchanged. This is because integers are value types, and so are passed by value; a copy is made as they are passed to GetTime( ), and the original values in Main( ) are left unchanged. What you need is to pass these values by reference.

Two small changes are required. First, change the parameters of the GetTime( ) method to indicate that the parameters are ref (reference) parameters:

public void GetTime(ref int h, ref int m, ref int s)
{
   h = Hour;
   m = Minute;
   s = Second;
}

Second, modify the call to GetTime( ) to pass the arguments as references:

t.GetTime(ref theHour, ref theMinute, ref theSecond);

The results will now show the correct time. By declaring these parameters to be ref parameters, you instruct the compiler to pass them by reference, and instead of a copy being made, the parameter in GetTime( ) will be a reference to the same variable (theHour) that was created in Main( ). When you change these values in GetTime( ), the change will be reflected in Main( ) because the references will be referring to the same values in memory.

Keep in mind that ref parameters are references to the actual original value: it is as though you said, “Here, work on this one.” Conversely, value parameters are copies: it is as though you said, “Here, work on one just like this.”

C# imposes definite assignment, which requires that all variables be assigned a value before they are used. In Example 4-8, if you don’t initialize theHour, theMinute, and theSecond before you pass them as parameters to GetTime( ), the compiler will complain. Yet, the initialization that is done merely sets their values to 0 before they are passed to the method:

int theHour = 0;
int theMinute = 0;
int theSecond = 0;
t.GetTime( ref theHour, ref theMinute, ref theSecond);

There is no logical reason to set these values to zero; our intent is to pass them to GetTime and have them set to a meaningful value there. The problem is that definite assignment won’t let unassigned variables be passed as parameters. If you try, you will receive the following compiler errors:

Use of unassigned local variable 'theHour'
Use of unassigned local variable 'theMinute'
Use of unassigned local variable 'theSecond'

One solution, as shown here, is to initialize the variables to a meaningless value−in this case, zero. But assigning a value should have semantic meaning within your program; it shouldn’t be done just to satisfy a technical requirement that doesn’t apply in this circumstance. That is why C# provides the out parameter modifier.

The out modifier suspends the requirement that a reference parameter be initialized. The parameters to GetTime( ), for example, provide no information to the method; they are simply a mechanism for getting information from the method. Thus, by marking all three as out parameters, you eliminate the need to initialize them outside the method.

The out parameter thus increases the self-documentation (and long-term reliability) of the program in two ways:

Within the called method, the out parameters must be assigned a value before the method returns (failure to do so will cause a compile error). The following are the altered parameter declarations for GetTime( ):

public void GetTime(out int h, out int m, out int s)
{
  h = Hour;
  m = Minute;
  s = Second;
}

And, here is the new invocation of the method in Main( ):

t.GetTime(out theHour, out theMinute, out theSecond);

To summarize, value types are passed into methods by value. ref parameters are used to pass value types into a method by reference. This allows you to retrieve their modified values in the calling method. out parameters are used only to return information from a method. Example 4-9 rewrites Example 4-8 to use all three.

using System;

namespace InOutRef
{
  public class Time
  {
    // private member variables
    private int Year;
    private int Month;
    private int Date;
    private int Hour;
    private int Minute;
    private int Second;

    // public accessor methods
    public void DisplayCurrentTime(  )
    {
      System.Console.WriteLine( "{0}/{1}/{2} {3}:{4}:{5}",
        Month, Date, Year, Hour, Minute, Second );
    }

    public int GetHour(  )
    {
      return Hour;
    }public void SetTime( int hr, out int min, ref int sec )
    {
      // if the passed in time is >= 30
      // increment the minute and set second to 0
      // otherwise leave both alone
      if ( sec >= 30 )
      {
        Minute++;
        Second = 0;
      }
      Hour = hr; // set to value passed in

      // pass the minute and second back out
      min = Minute;
      sec = Second;
    }

    // constructor
    public Time( System.DateTime dt )
    {
      Year = dt.Year;
      Month = dt.Month;
      Date = dt.Day;
      Hour = dt.Hour;
      Minute = dt.Minute;
      Second = dt.Second;
    }
  }

  public class Tester
  {
    static void Main(  )
    {
      System.DateTime currentTime = System.DateTime.Now;
      Time t = new Time( currentTime );
      t.DisplayCurrentTime(  );

      int theHour = 3;
      int theMinute;
      int theSecond = 20;

      t.SetTime( theHour, out theMinute, ref theSecond );
      System.Console.WriteLine(
        "the Minute is now: {0} and {1} seconds",
        theMinute, theSecond );

      theSecond = 40;
      t.SetTime( theHour, out theMinute, ref theSecond );
      System.Console.WriteLine( "the Minute is now: " +
        "{0} and {1} seconds", theMinute, theSecond );
    }
  }
}

Output:
11/17/2007 14:6:24
the Minute is now: 6 and 24 seconds
the Minute is now: 7 and 0 seconds

SetTime is a bit contrived, but it illustrates the three types of parameters. theHour is passed in as a value parameter; its entire job is to set the member variable Hour, and no value is returned using this parameter.

The ref parameter theSecond is used to set a value in the method. If theSecond is greater than or equal to 30, the member variable Second is reset to 0 and the member variable Minute is incremented.

Finally, theMinute is passed into the method only to return the value of the member variable Minute, and thus is marked as an out parameter.

It makes perfect sense that theHour and theSecond must be initialized—their values are needed and used. It is not necessary to initialize theMinute, as it is an out parameter that exists only to return a value. What at first appeared to be arbitrary and capricious rules now make sense; values are required to be initialized only when their initial value is meaningful.

The body of the get accessor is similar to a class method that returns an object of the type of the property. In the example, the accessor for Hour is similar to a method that returns an int. It returns the value of the private member variable in which the value of the property has been stored:

get
{
  return hour;
}

In this example, a local int member variable is returned, but you could just as easily retrieve an integer value from a database, or compute it on the fly.

Whenever you read the property, the get accessor is invoked:

Time t = new Time(currentTime);
int theHour = t.Hour;

In this example, the value of the Time object’s Hour property is retrieved, invoking the get accessor to extract the property, which is then assigned to a local variable.

The set accessor sets the value of a property and is similar to a method that returns void. When you define a set accessor, you must use the value keyword to represent the argument whose value is passed to and stored by the property:

set
{
  hour = value;
}

Here again, a private member variable is used to store the value of the property, but the set accessor could write to a database or update other member variables as needed.

When you assign a value to the property, the set accessor is automatically invoked, and the implicit parameter value is set to the value you assign:

theHour++;
t.Hour = theHour;

The two main advantages of this approach are that the client can interact with the properties directly, without sacrificing the data-hiding and encapsulation sacrosanct in good object-oriented design, and that the author of the property can ensure that the data provided is valid.

It is possible to set an access modifier (protected, internal, private) to modify access to either the get or set accessor. To do so, your property must have both a set and a get accessor, and you may modify only one or the other. Also, the modifier must be more restrictive than the accessibility level already on the property or the indexer (thus, you may add protected to the get or set accessor of a public property, but not to a private property):

public string MyString
{
  protected get { return myString; }
  set { myString = value; }
}

In this example, access to the get accessor is restricted to methods of this class and classes derived from this class, whereas the set accessor is publicly visible.