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).
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
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.
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
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.
refandoutneed an assignable location: a local, field, array element orrefreturn. A property or a literal does not work.inalso accepts rvalues because the compiler makes a temporary. - Overloads. You can overload a by-value parameter against
ref,outorin, butrefandoutcannot 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,outorinparameters (CS1988 for async), because their state is moved off the stack acrossawaitandyield. - Pattern:
Try...The idiombool 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.
inhelps 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 structreadonlyso the compiler does not copy it defensively when you call its members. - Do not hold
refs too long. Arefto a local cannot escape the method; the compiler enforces this with escape analysis (CS8168 and related errors). outfor deconstruction-like APIs.Dictionary.TryGetValueandint.TryParseare 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.