The StringBuilder class produces strings that can be changed.

For example, the following code declares and initializes a string of type StringBuilder and prints its value. The fourth line changes the actual object by replacing part of the string. Now when you print its value, you can see that, unlike an object of type string, the StringBuilder object has actually been changed.

using System.Text;

   StringBuilder sb = new StringBuilder("Hi there.");
   Console.WriteLine("{0}", sb);                 // Print string
   sb.Replace("Hi", "Hello");                    // Replace a substring
   Console.WriteLine("{0}", sb);                 // Print changed string

This code produces the following output:

Hi there.
Hello there.

When a StringBuilder object is created, the class allocates a buffer longer than the actual current string length. As long as the changes made to the string can fit in the buffer, no new memory is allocated. If changes to the string require more space than is available in the buffer, a new, larger buffer is allocated, and the string is copied to it. Like the original buffer, this new buffer also has extra space.

To get the string corresponding to the StringBuilder content, you simply call its ToString method.

Throughout the text, the sample code has used the WriteLine method to display values. Each time, it used the simple substitution marker consisting of curly braces surrounding an integer. Many times, however, you will want to present the output of a text string in a format more appropriate than just a plain number. For example, you might want to display a value as currency or as a fixed-point value with a certain number of decimal places. You can do these things by using format strings.

For example, the following code consists of two statements that print out the value 500. The first line prints out the number without any additional formatting. In the second line, the format string specifies that the number should be formatted as currency.

This code produces the following output:

The value: 500.
The value: $500.00.

The difference between the two statements is that the format item includes additional information in the form of a format specifier. The syntax for a format specifier consists of three fields inside the set of curly braces: the index, the alignment specifier, and the format specifier. The syntax is shown in Figure 25-1.

Figure 25-1. Syntax for a format item

The first thing in the format item is the index. As you well know by now, the index specifies which item from the list following the format string should be formatted. The index is required, and numbering of the list items starts at 0.

The Alignment Specifier

The alignment specifier represents the minimum width of the field in terms of characters. The alignment specifier has the following characteristics:

• It is optional and separated from the index with a comma.

• It consists of a positive or negative integer.

  • The integer represents the minimum number of characters to use for the field.

  • The sign represents either right or left alignment. Positive specifies right alignment; negative specifies left alignment.

For example, the following code shows two format items, formatting the value of int variable myInt. In the first case, the value of myInt is displayed as a right-aligned string of ten characters. In the second case, it is left-aligned. The format items are between two vertical bars, just to show in the output their limits on each side.

int myInt = 500;
   Console.WriteLine("|{0, 10}|", myInt);                 // Aligned right
   Console.WriteLine("|{0,-10}|", myInt);                 // Aligned left

This code produces the following output; there are ten characters between the vertical bars:

|       500|
|500       |

The actual representation of the value might take more or fewer characters than specified in the alignment specifier:

• If the representation takes fewer characters than specified in the alignment specifier, the remaining characters are padded with spaces.

• If the representation takes more characters than specified, the alignment specifier is ignored, and the representation uses as many characters as is needed.

The Format Component

The format component specifies the form that the numeric representation should take. For example, should it be represented as currency, in decimal format, in hexadecimal format, or in fixed-point notation?

The format component has two parts, as shown in Figure 25-2:

• The format specifier is a single alphabetic character, from a set of nine built-in character formats. The character can be uppercase or lowercase. The case is significant for some specifiers, but not for others.

• The precision specifier is optional, and consists of one or two digits. Its actual meaning depends on the format specifier.

Figure 25-2. Standard format specifier string

The following code shows an example of the syntax of the format string component:

Some examples of different format strings are shown in the following code:

double myDouble = 12.345678;
   Console.WriteLine("{0,-10:G} -- General",                      myDouble);
   Console.WriteLine("{0,-10} -- Default, same as General",       myDouble);
   Console.WriteLine("{0,-10:F4} -- Fixed Point, 4 dec places",   myDouble);
   Console.WriteLine("{0,-10:C} -- Currency",                     myDouble);
   Console.WriteLine("{0,-10:E3} -- Sci. Notation, 3 dec places", myDouble);
   Console.WriteLine("{0,-10:x} -- Hexadecimal integer",          1194719 );

This code produces the following output:

12.345678  -- General
12.345678  -- Default, same as General
12.3457    -- Fixed Point, 4 dec places
$12.35     -- Currency
1.235E+001 -- Sci. Notation, 3 dec places
123adf     -- Hexadecimal integer

A nullable type is always based on another type, called the underlying type, that has already been declared.

To create a variable of a nullable type, simply add a question mark to the end of the name of the underlying type, in the variable declaration. Unfortunately, this syntax makes it appear that you have a lot of questions about your code.

For example, the following code declares a variable of the nullable int type. Notice that the suffix is attached to the type name—not the variable name.

With this declaration statement, the compiler takes care of both producing the nullable type and the variable of that type. Figure 25-3 shows the structure of this nullable type. It contains the following:

Figure 25-3. A nullable type contains an object of the underlying type in a struct, with two read-only properties.

You can use the two read-only properties explicitly as follows:

A better method, however, is to use the shortcut forms, as shown in the following code.

Both sets of code produce the following output:

15

Reading a variable of a nullable type returns its value. You must, however, make sure that the variable is not null. Attempting to read the value of a null variable produces an exception.

You can easily convert between a nullable type and its corresponding non-nullable type.

For example, the following lines show conversion in both directions. In the first line, a literal of type int is implicitly converted to a value of type int? and is used to initialize the variable of the nullable type. In the second line, the variable is explicitly converted to its non-nullable version.

int? myInt1 = 15;                       // Implicitly convert int to int?
   int  regInt = (int) myInt1;             // Explicitly convert int? to int

There are three kinds of values you can assign to a variable of a nullable type:

The following code shows an example of each of the three types of assignment:

int? myI1, myI2, myI3;

   myI1 = 28;                                   // Value of underlying type
   myI2 = myI1;                                 // Value of nullable type
   myI3 = null;                                 // Null

   Console.WriteLine("myI1: {0}, myI2: {1}", myI1, myI2);
   Console.WriteLine("myI3 {0} null", myI3 == null ? "is" : "is not");

This code produces the following output:

myI1: 28, myI2: 28
myI3 is null

Using Operators and the Null Coalescing Operator

The standard arithmetic and comparison operators also handle nullable types. There is also a new operator called the null coalescing operator, which allows you to return a value to an expression, in case a nullable type variable is null.

The null coalescing operator consists of two contiguous question marks and has two operands:

• The first operand is a variable of a nullable type.

• The second is a non-nullable value of the same underlying type.

• If, at run time, the first operand evaluates to null, the second operand is returned as the result of the operation.

This code produces the following output:

myI4: −1
myI4: 10

The equality comparison operators, == and !=, have an interesting characteristic you need to be aware of. If you compare two values of the same nullable type, and both are null, the equality comparison operators consider them equal. For example, in the following code, the two nullable ints are set to null. The equality comparison operator will declare them equal.

int? i1 = null, i2 = null;                       // Both are null.

   if (i1 == i2)                                    // Operator returns true.
      Console.WriteLine("Equal");

So far, you have seen nullable forms of the predefined, simple types. You can also create nullable forms of user-defined value types. These bring up additional issues that don't come up when using the simple types.

The main issue is access to the members of the encapsulated underlying type. A nullable type doesn't directly expose any of the members of the underlying type. For example, take a look at the following code and its representation in Figure 25-4. The code declares a struct (which is a value type) called MyStruct, with two public fields.

struct MyStruct                                        // Declare a struct.
{
   public int X;                                       // Field
   public int Y;                                       // Field
   public MyStruct(int xVal, int yVal)                 // Constructor
   { X = xVal;  Y = yVal; }
}

class Program {
   static void Main()
   {
      MyStruct? mSNull = new MyStruct(5, 10);
      ...

Figure 25-4. The accessibility of the members of a struct is different from that of the nullable type.

For example, the following code uses the previously declared struct and creates variables of both the struct and the corresponding nullable type. In the third and fourth lines of code, the values of the struct's variables are read directly. In the fifth and sixth lines, they must be read from the value returned by the nullable's Value property.

Nullable<MyStruct> mSNull = new Nullable<MyStruct>();

MyStruct? mSNull = new MyStruct();

Main can be declared public or private:

The execution environment, however, always has access to Main, regardless of its declared access level, or the declared access level of the class or struct in which it is declared.

By default, when Visual Studio creates a project, it creates a program outline where Main is implicitly private. You can always add the public modifier if you need to.

Documentation comments start with three consecutive forward slashes.

For example, in the following code, the first four lines show documentation comments about the class declaration. They use the <summary> XML tag. Above the declaration of the field are three lines documenting the field—again using the <summary> tag.

Each XML element is inserted by Visual Studio automatically when you type three slashes above the declaration of a language feature, such as a class or a class member.

For example, the following code shows two slashes above the declaration of class MyClass:

//
   class MyClass
   { ...

As soon as you add the third slash, Visual Studio immediately expands the comment to the following code, without your having to do anything. You can then type anything you want on the documentation comment lines between the tags.

/// <summary>        Automatically inserted
   ///                  Automatically inserted
   /// </summary>       Automatically inserted
   class MyClass
   { ...

In the preceding examples, you saw the use of the summary XML tag. There are also a number of other tags that C# recognizes. Some of the most important are listed in Table 25-3.

The following code fleshes out classes MyClass and MyCounter into a full program. MyCounter implements an integer counter that starts at 0 and can be incremented using the ++ operator. When the constructor for MyClass is called, it creates an instance of the nested class and assigns the reference to the field. Figure 25-7 illustrates the structure of the objects in the code.

class MyClass
   {
      class MyCounter                                      // Nested class
      {
         private int _Count = 0;
         public int Count                                  // Read-only property
         {
            get { return _Count; }
         }

         public static MyCounter operator++( MyCounter current )
         {
            current._Count++;
            return current;
         }
      }

      private MyCounter counter;                         // Field of nested class

      public MyClass() { counter = new MyCounter(); }    // Constructor

      public int Incr()     { return (counter++).Count; }  // Increment method
      public int GetValue() { return counter.Count; }      // Get counter value
   }

   class Program
   {
      static void Main( )
      {
         MyClass mc = new MyClass();                       // Create object

         mc.Incr(); mc.Incr(); mc.Incr();                  // Increment it.
         mc.Incr(); mc.Incr(); mc.Incr();                  // Increment it.

         Console.WriteLine("Total:  {0}", mc.GetValue());  // Print its value.
      }
   }

This code produces the following output:

Total:  6

Figure 25-7. Objects of a nested class and its enclosing class

In Chapter 7, you learned that classes, and types in general, can have an access level of either public or internal. Nested types, however, are different in that they have member accessibility rather than type accessibility. Therefore, the following are true:

In both cases, the default access level of a nested type is private, which means it cannot be seen outside the enclosing type.

The relationship between the members of the enclosing class and the nested class is a little less straightforward, and is illustrated in Figure 25-8. The nested type has complete access to the members of the enclosing type, regardless of their declared accessibility, including members that are private and protected.

The relationship, however, is not symmetrical. Although the members of the enclosing type can always see the nested type declaration and create variables and instances of it, they do not have complete access to its members. Instead, their access is limited to the declared access of the nested class members—just as if the nested type were a separate type. That is, they can access the public and internal members, but cannot access the private or protected members of the nested type.

Figure 25-8. Accessibility between nested type members and enclosing type members

You can summarize this relationship as follows:

The visibility of nested types can also affect the inheritance of base members. If the enclosing class is a derived class, a nested type can hide a base class member with the same name. Use the new modifier with the declaration of the nested class to make the hiding explicit.

A this reference within a nested type refers to the object of the nested type—not the object of the enclosing type. If an object of the nested type needs access to the enclosing type, it must have a reference to it. You can have the enclosing object supply its this reference as a parameter to the nested type's constructor, as shown in the following code:

This codeproducesthe following output:

Field1: 15
Field2: 20