Skip to content
Tutorials Center
My learning

Topics

C# Reference ยท Keywords and Statements

ref, out and in parameter modifiers

Reference for C# ref, out, in and ref readonly parameters: passing by reference, output parameters, discards, out var, rules, errors and performance.

By default C# passes arguments by value: the method receives a copy of a value type, or a copy of the reference to a class instance. Three modifiers change that and pass a reference to the caller's variable instead.

  • ref: the variable must be initialized by the caller; the method may read and write it.
  • out: the variable need not be initialized; the method must assign it before returning.
  • in: the variable is passed by reference for speed, but the method may only read it.

The same keyword must appear at the call site (except for in, where it is optional).

C#
void Swap(ref int a, ref int b) => (a, b) = (b, a);
bool TryParse(string s, out int value) { ... }
double Length(in Vector big) { ... }

Try it

C# ref and out

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

C# in and ref locals for large structs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Syntax

C#
void M(ref T p)         // call: M(ref variable)
void M(out T p)         // call: M(out variable), M(out T v), M(out var v), M(out _)
void M(in T p)          // call: M(variable), M(in variable), M(expression)
void M(ref readonly T p) // C# 12: call M(ref variable) or M(in variable)
ref T M(...)            // ref return
ref T local = ref expr; // ref local
Modifier Caller must initialize Callee must assign Callee may write Call-site keyword
ref yes no yes ref required
out no yes, before every normal return yes out required
in yes no no in optional
ref readonly yes no no ref or in

Errors: reading an out parameter before assigning it is CS0269; returning without assigning it is CS0177; passing an uninitialized variable to ref is CS0165; omitting ref/out at the call is CS1620; passing a literal or property to ref is CS1510; writing to an in parameter is CS8331 (CS8332 for one of its fields).

Usage notes

  • Argument must be a variable. ref and out need an assignable location: a local, field, array element or ref return. A property or a literal does not work. in also accepts rvalues because the compiler makes a temporary.
  • Overloads. You can overload a by-value parameter against ref, out or in, but ref and out cannot be the only difference between two overloads (CS0663). A call without a modifier picks the by-value overload.
  • Not allowed in async methods or iterators. They cannot have ref, out or in parameters (CS1988 for async), because their state is moved off the stack across await and yield.
  • Pattern: Try... The idiom bool TryX(..., out T result) returns success and gives a default result on failure. It avoids exceptions in hot paths. Tuples are often a cleaner alternative when failure is not expected.
  • Performance. in helps with large structs (more than about 16 to 24 bytes) by avoiding a copy; for small structs and classes it is slower or equal. Make the struct readonly so the compiler does not copy it defensively when you call its members.
  • Do not hold refs too long. A ref to a local cannot escape the method; the compiler enforces this with escape analysis (CS8168 and related errors).
  • out for deconstruction-like APIs. Dictionary.TryGetValue and int.TryParse are the classic cases.
  • ref returns and locals let a method hand out a reference to an array element or field; the caller can then modify it in place.