.CS File Format – Variables

Variable categories

A field of a struct variable belongs to that variable’s category. In a struct variable, the instance variables are assigned when the struct variable is. A local variable may be in a block, a for, foreach, using, fixed or catch header, or be created by a pattern or an out argument.

Local variables

int a;                 // declared, unassigned
int b = 1, c = 2;      // several in one declaration
var d = 1.5;           // inferred as double
const int Max = 10;    // a local constant
using var file = File.OpenRead(path);  // disposed at the end of the scope

A local variable’s scope is the block it is declared in, including any part of the block before the declaration. It cannot be used before its declaration, and a nested block cannot declare the same name while the variable is in scope. Since C# 8, the parameters of a lambda, anonymous method or local function may shadow outer names.

_ = Compute();                         // ignores the result
int.TryParse(text, out _);             // ignores an out value
var (first, _) = GetPair();            // ignores a deconstructed value

Definite assignment

A local variable, or an out parameter, must be definitely assigned before it is read (clause 9.4). The compiler works this out by flow analysis at every statement and expression. It does not evaluate conditions, except constants.

int a;
if (cond) a = 1; else a = 2;
Console.WriteLine(a);            // fine: assigned on both paths

int b;
if (cond) b = 1;
Console.WriteLine(b);            // error: unassigned on the other path

int c;
if (x > 0 && (c = x) > 0)
    Console.WriteLine(c);        // fine: && assigned c on the true path

int d;
while (true) { d = 1; break; }
Console.WriteLine(d);            // fine: while (true) ends only through the break

• Static variables, instance variables and array elements are always assigned.
• An out parameter must be assigned before the method returns normally. A method that always throws has no such obligation.
• For a struct variable, each field is tracked separately until all are assigned.
• Inside a struct constructor, this must be fully assigned before use. Since C# 11, fields not assigned by a constructor are set to their default values, so a struct constructor need not assign every field.
• Variables captured by a lambda, or declared in a try, follow the rules of clauses 9.4.4.14 to 9.4.4.16 and 9.4.4.31: assignment in a try block is not definite in the matching catch.

Parameters

A method’s parameters can be passed in five ways (clause 15.6.2).

• out var x declares the variable in the argument list (C# 7.0). Its scope is the enclosing block, so it can be read after the call.
• An in argument may be a value, in which case a temporary is created. A ref readonly parameter expects a variable, and the compiler warns if given a value.
• A by-reference parameter and a by-value parameter are different for overloading, but two overloads cannot differ only in which of ref, in, ref readonly and out they use.
• in and ref readonly stop the method writing through the parameter. If a method called on such a struct parameter might change it, the compiler makes a defensive copy.

static int Sum(params ReadOnlySpan<int> values)
{
    int total = 0;
    foreach (int v in values) total += v;
    return total;
}

Sum();                   // empty
Sum(1, 2, 3);            // three arguments

void Draw(int x, int y = 0, string color = "red") { }

Draw(1);
Draw(1, color: "blue");   // skips y
Draw(y: 2, x: 1);

Reference variables and returns

A reference variable is an alias for another variable. Reference parameters are one kind; ref locals and ref returns are the others (C# 7.0, clause 9.7).

int[] data = { 1, 2, 3 };

ref int first = ref data[0];         // ref local
first = 9;                           // data[0] is now 9

first = ref data[1];                 // ref reassignment, C# 7.3

ref readonly int r = ref data[2];    // cannot be used to write

ref int Max(ref int a, ref int b)    // ref return
{
    if (a > b) return ref a;
    return ref b;
}

Max(ref data[0], ref data[1]) = 0;   // assigns to the larger

ref int e = ref (cond ? ref data[0] : ref data[1]);   // ref conditional, C# 7.2

• ref appears both at the declaration and on the assignment of a ref local.
• A foreach can use ref or ref readonly variables when the enumerator’s Current returns by reference.
• Since C# 13, ref locals may be used in iterators and async methods, within restrictions: not across a yield return or an await.
• A ref field exists only in a ref struct.

Span<int> Keep(scoped Span<int> values)
{
    values[0] = 1;          // fine: values is used only inside the method
    return values;          // error: values cannot escape this method
}

Atomicity

Reads and writes of bool, char, byte, sbyte, short, ushort, int, uint, float, reference types and enums based on those are atomic. Other types, including long, ulong, double, decimal and user structs, have no such guarantee (clause 9.6). A combined read and write such as i++ is never atomic. Interlocked in System.Threading provides atomic read-modify-write operations.