Out

The C# out-keyword signifies a reference parameter. Sometimes methods must return more than one value, or modify a value argument passed to them.

The out-modifier fills these requirements. With it, we pass parameters whose changes are realized in their calling methods. In a method, an out-argument must be assigned.

Example

The C# language has robust support for object-oriented logic. But it also provides a way to return many values from a method without using objects.

using System;

class Program
{
    static void Main()
    {
        // Part 1: variables used as out parameter.
        bool period;
        bool comma;
        bool semicolon;
        const string value = "has period, comma.";

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

        Console.WriteLine(value);
        Console.Write("period: ");
        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)
    {
        // Part 2: assign all out parameters to false.
        period = comma = semicolon = 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;
                    }
            }
        }
    }
}
has period, comma.
period: True
comma: True
semicolon: False

Inline out-parameters

We can combine statements when calling a method that requires an out-parameter. We can declare the variable directly inline with the method call.

using System;

class Program
{
    static bool Test(out int size)
    {
        // This method has an out parameter.
        size = 1000;
        return size >= 1000;
    }

    static void Main()
    {
        // Declare out parameter directly inside method call.
        if (Test(out int size))
        {
            Console.WriteLine(size);
        }
    }
}
1000

Discard name syntax

Sometimes we need to call a method with out-parameters, but do not need to use those parameters. We can avoid using a "dummy" name for those locals.

using System;

class Program
{
    static void Test(out int size, out string name)
    {
        size = 10;
        name = "bird";
    }

    static void Main()
    {
        // We do not need the out int, so use an underscore name (discard name).
        Test(out _, out string name);
        Console.WriteLine("NAME: {0}", name);
    }
}
NAME: bird

Discussion

The out-descriptor tells the intermediate language compiler to copy the actual variable storage location, not just the value at a storage location.

Definite assignment

The C# compiler applies definite assignment analysis. The out-keyword ensures that variables are always assigned in the body of a method.

With the out-modifier, a method can signal to the calling location that the variable was initialized and written. This simplifies code that returns values.