C# Out Parameter

Out signifies a reference parameter. Sometimes methods must return more than one value and not store class state. The out descriptor in the C# language is an excellent way to fill these requirements. It provides a way to pass output parameters whose changes are realized in their calling methods.

Example

The .NET Framework provides robust support for not creating object-oriented logic that concentrates on storing multiple values as fields in classes, but it also provides a way to return many values from a method without using objects.

The out-keyword in the language describes parameters whose actual variable locations are copied onto the stack of the called method, where those same locations can be rewritten. This means that the calling method will access the changed parameter.

This C# example program shows how to use the out keyword on arguments.

Program that uses out Boolean parameters [C#]

using System;

class Program
{
    static void Main()
    {
	bool period; // Used as out parameter
	bool comma;
	bool semicolon;
	const string value = "has period, comma."; // Used as input string

	TestString(value, out period, out comma, out semicolon);

	Console.WriteLine(value); // Display value
	Console.Write("period: "); // Display labels and bools
	Console.WriteLine(period);
	Console.Write("comma: ");
	Console.WriteLine(comma);
	Console.Write("semicolon: ");
	Console.WriteLine(semicolon);
    }

    static void TestString(string value, out bool period, out bool comma, out bool semicolon)
    {
	period = comma = semicolon = false; // Assign all out parameters to false

	for (int i = 0; i < value.Length; i++)
	{
	    switch (value[i])
	    {
		case '.':
		    {
			period = true; // Set out parameter
			break;
		    }
		case ',':
		    {
			comma = true; // Set out parameter
			break;
		    }
		case ';':
		    {
			semicolon = true; // Set out parameter
			break;
		    }
	    }
	}
    }
}

Output

has period, comma.
period: True
comma: True
semicolon: False

Overview. The example program defines a Program class with two enclosed static method. The Main entry point is where the program execution begins. In the Main method, three local bool variables are declared but not initialized. Those same bool variable locations on the stack are initialized to the false Boolean literal in the TestString method called next. In the loop in TestString, if certain characters occur in the string, the bool parameters are assigned true.

Calling pattern. The TestString method as shown can be used in certain kinds of programs that want to find multiple properties of the string in a single pass through the string's characters. Although you could search for each character individually, this would incur more overhead. This method provides a way for the calling method to query if the string has any of the specified characters, and which ones.

Out value parameters. The out descriptor tells the intermediate language compiler to copy the actual variable storage location, not just the value at a storage location. Out parameters are often most useful for value types such as bool because there is no other easy way to return multiple values without allocating an array or object.

Definite assignment analysis

The C# compiler applies the concept of definite assignment analysis in this application. In the program, the three Boolean values are uninitialized and are never assigned in the Main method body. However, the out keyword demands that they are definitely assigned (always assigned) in the body of the TestString method.

Note: The compiler knows that the three Boolean variables are always set to an explicit true or false value when the TestString method returns and control flow returns to the location after the method call.

Summary

We saw a method that uses the keyword out in the C# language as a way for one method to signal to the calling location that the variable location's were initialized and written to in the method. The out keyword is most useful for value types and where object-oriented methodologies are not convenient or worth applying. The out keyword can simplify code where multiple function calls can be combined into a single function call that returns all of the relevant values.