Skip to content

Commit 93ce762

Browse files
authored
rewrite paragraph on ref locals` (#33778)
Rework this paragraph for a better explanation of `ref` locals vs. value locals. Fixes #33417
1 parent ebf7feb commit 93ce762

File tree

1 file changed

+6
-11
lines changed

1 file changed

+6
-11
lines changed

docs/csharp/language-reference/statements/declarations.md

Lines changed: 6 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "Declaration statements - var, ref local variables, and ref fields"
33
description: "Declarations introduce a new variable. These statements include `var`, `ref` locals, and `ref` fields. In addition to declaring a new variable, these statements can initialize that variable's value."
4-
ms.date: 11/22/2022
4+
ms.date: 01/30/2023
55
f1_keywords:
66
- "var"
77
- "var_CSharpKeyword"
@@ -45,27 +45,22 @@ The following example shows two query expressions. In the first expression, the
4545

4646
## Ref locals
4747

48-
You add the `ref` keyword before the type of a variable to declare a `ref` local. Assume the `GetContactInformation` method is declared as a [ref return](jump-statements.md#ref-returns):
48+
You add the `ref` keyword before the type of a variable to declare a `ref` local. A `ref` local is a variable that *refers to* other storage. Assume the `GetContactInformation` method is declared as a [ref return](jump-statements.md#ref-returns):
4949

5050
```csharp
5151
public ref Person GetContactInformation(string fname, string lname)
5252
```
5353

54-
A by-value assignment reads the value of a variable and assigns it to a new variable:
54+
Let's contrast these two assignments:
5555

5656
```csharp
5757
Person p = contacts.GetContactInformation("Brandie", "Best");
58+
ref Person p2 = ref contacts.GetContactInformation("Brandie", "Best");
5859
```
5960

60-
The preceding assignment declares `p` as a local variable. Its initial value is copied from reading the value returned by `GetContactInformation`. Any future assignments to `p` won't change the value of the variable returned by `GetContactInformation`. The variable `p` is no longer an alias to the variable returned.
61+
The variable `p` holds a *copy* of the return value from `GetContactInformation`. It's a separate storage location from the `ref` return from `GetContactInformation`. If you change any property of `p`, you are changing a copy of the `Person`.
6162

62-
You declare a *ref* variable to copy the alias to the original value. In the following assignment, `p` is an alias to the variable returned from `GetContactInformation`.
63-
64-
```csharp
65-
ref Person p = ref contacts.GetContactInformation("Brandie", "Best");
66-
```
67-
68-
Subsequent usage of `p` is the same as using the variable returned by `GetContactInformation` because `p` is an alias for that variable. Changes to `p` also change the variable returned from `GetContactInformation`.
63+
The variable `p2` *refers to* the storage location for the `ref` return from `GetContactInformation`. It's the same storage as the `ref` return from `GetContactInformation`. If you change any property of `p2`, you are changing that single instance of a `Person`.
6964

7065
You can access a value by reference in the same way. In some cases, accessing a value by reference increases performance by avoiding a potentially expensive copy operation. For example, the following statement shows how one can define a ref local value that is used to reference a value.
7166

0 commit comments

Comments
 (0)