Skip to content

Commit 4227c86

Browse files
skycommandsdwheeler
skycommand
authored and
sdwheeler
committed
about_Ref.md: Relationship between [ref] and [PSReference]
Added a new section, "Relationship between [ref] and System.Management.Automation.PSReference" to about_Ref.md.
1 parent 7bdebdd commit 4227c86

File tree

3 files changed

+174
-21
lines changed

3 files changed

+174
-21
lines changed

‎reference/5.1/Microsoft.PowerShell.Core/About/about_Ref.md‎

Lines changed: 57 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,6 @@ online version: https://learn.microsoft.com/powershell/module/microsoft.powershe
66
schema: 2.0.0
77
title: about_Ref
88
---
9-
109
# about_Ref
1110

1211
## Short description
@@ -17,9 +16,9 @@ of a variable that is passed to it.
1716

1817
## Long description
1918

20-
You can pass variables to functions *by reference* or *by value*.
19+
You can pass variables to functions _by reference_ or _by value_.
2120

22-
When you pass a variable *by value*, you are passing a copy of the data.
21+
When you pass a variable _by value_, you are passing a copy of the data.
2322

2423
In the following example, the function changes the value of the variable passed
2524
to it. In PowerShell, integers are value types so they are passed by value.
@@ -42,9 +41,9 @@ $var
4241

4342
In the following example, a variable containing a `Hashtable` is passed to a
4443
function. `Hashtable` is an object type so by default it is passed to the
45-
function *by reference*.
44+
function _by reference_.
4645

47-
When passing a variable *by reference*, the function can change the data and
46+
When passing a variable _by reference_, the function can change the data and
4847
that change persists after the function executes.
4948

5049
```powershell
@@ -71,10 +70,10 @@ scope.
7170

7271
You can code your functions to take a parameter as a reference, regardless of
7372
the type of data passed. This requires that you specify the parameters type
74-
as `System.Management.Automation.PSReference`, or `[ref]`.
73+
as `[ref]`.
7574

76-
When using references, you must use the `Value` property of the
77-
`System.Management.Automation.PSReference` type to access your data.
75+
When using references, you must use the `Value` property of the `[ref]` type to
76+
access your data.
7877

7978
```powershell
8079
Function Test([ref]$data)
@@ -86,7 +85,7 @@ Function Test([ref]$data)
8685
To pass a variable to a parameter that expects a reference, you must type
8786
cast your variable as a reference.
8887

89-
> [!NOTE]
88+
> [!IMPORTANT]
9089
> The brackets and parenthesis are BOTH required.
9190
9291
```powershell
@@ -149,10 +148,59 @@ $i = 0;$iRef = 1
149148

150149
Only the reference type's variable was changed.
151150

151+
### Relationship between [ref] and System.Management.Automation.PSReference
152+
153+
`Ref` is both a type accelerator for `System.Management.Automation.PSReference`
154+
(see [about_Type_Accelerators] for details) and a reserved keyword that
155+
PowerShell treats especially. Hence, `ref` and `PSReference` are not
156+
equivalents. The following script demonstrates their difference:
157+
158+
```powershell
159+
$x = 1
160+
161+
$a = [ref] $x
162+
$b = [System.Management.Automation.PSReference] $x
163+
$c = [ref] $x
164+
165+
$x +=4
166+
$a.Value +=3
167+
$b.Value +=2
168+
$c.Value +=1
169+
170+
$x, $a.Value, $b.Value, $c.Value | ForEach-Object {
171+
Write-Output $PSItem
172+
}
173+
```
174+
175+
The output of this script is:
176+
177+
```powershell
178+
9
179+
9
180+
3
181+
9
182+
```
183+
184+
The above script:
185+
186+
- Creates an integer `$x` variable and assigns `1` to it.
187+
- Creates pointers `$a` and `$c` of `[ref]` types and points them at `$x`.
188+
- Creates pointer `$b` of `[PSReference]` type and points it, not at `$x`, but
189+
a copy thereof, because PowerShell treats `[ref]` and `[PSReference]`
190+
differently.
191+
- Adds 4 to `$x`, 3 to `$a`'s value, 2 to `$b`'s value, and 1 to `$a`'s value.
192+
193+
In the script above, `$x`, `$a.Value`, and `$c.Value` point to the same memory
194+
location. They are the same, i.e., 1 + 4 + 3 + 1 = 9. But `$b.Value` refers to
195+
a copy of `$x` at the time of its creation. Hence, it contains 1 + 2 = 3.
196+
152197
## See also
153198

154199
- [about_Variables](about_Variables.md)
155200
- [about_Environment_Variables](about_Environment_Variables.md)
156201
- [about_Functions](about_Functions.md)
157202
- [about_Script_Blocks](about_Script_Blocks.md)
158203
- [about_Scopes](about_scopes.md)
204+
- [about_Type_accelerators]
205+
206+
[about_Type_accelerators]: about_Type_Accelerators.md

‎reference/7.4/Microsoft.PowerShell.Core/About/about_Ref.md‎

Lines changed: 61 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -9,15 +9,16 @@ title: about_Ref
99
# about_Ref
1010

1111
## Short description
12+
1213
Describes how to create and use a reference type variable. You can use
1314
reference type variables to permit a function to change the value
1415
of a variable that is passed to it.
1516

1617
## Long description
1718

18-
You can pass variables to functions *by reference* or *by value*.
19+
You can pass variables to functions _by reference_ or _by value_.
1920

20-
When you pass a variable *by value*, you are passing a copy of the data.
21+
When you pass a variable _by value_, you are passing a copy of the data.
2122

2223
In the following example, the function changes the value of the variable passed
2324
to it. In PowerShell, integers are value types so they are passed by value.
@@ -40,9 +41,9 @@ $var
4041

4142
In the following example, a variable containing a `Hashtable` is passed to a
4243
function. `Hashtable` is an object type so by default it is passed to the
43-
function *by reference*.
44+
function _by reference_.
4445

45-
When passing a variable *by reference*, the function can change the data and
46+
When passing a variable _by reference_, the function can change the data and
4647
that change persists after the function executes.
4748

4849
```powershell
@@ -69,10 +70,10 @@ scope.
6970

7071
You can code your functions to take a parameter as a reference, regardless of
7172
the type of data passed. This requires that you specify the parameters type
72-
as `System.Management.Automation.PSReference`, or `[ref]`.
73+
as `[ref]`.
7374

74-
When using references, you must use the `Value` property of the
75-
`System.Management.Automation.PSReference` type to access your data.
75+
When using references, you must use the `Value` property of the `[ref]` type to
76+
access your data.
7677

7778
```powershell
7879
Function Test([ref]$data)
@@ -84,7 +85,7 @@ Function Test([ref]$data)
8485
To pass a variable to a parameter that expects a reference, you must type
8586
cast your variable as a reference.
8687

87-
> [!NOTE]
88+
> [!IMPORTANT]
8889
> The brackets and parenthesis are BOTH required.
8990
9091
```powershell
@@ -147,10 +148,62 @@ $i = 0;$iRef = 1
147148

148149
Only the reference type's variable was changed.
149150

151+
### Relationship between [ref] and System.Management.Automation.PSReference
152+
153+
`Ref` is both a type accelerator for `System.Management.Automation.PSReference`
154+
(see [about_Type_Accelerators] for details) and a reserved keyword that
155+
PowerShell [treats][2] [especially][1]. Hence, `ref` and `PSReference` are not
156+
equivalents. The following script demonstrates their difference:
157+
158+
```powershell
159+
$x = 1
160+
161+
$a = [ref] $x
162+
$b = [System.Management.Automation.PSReference] $x
163+
$c = [ref] $x
164+
165+
$x +=4
166+
$a.Value +=3
167+
$b.Value +=2
168+
$c.Value +=1
169+
170+
$x, $a.Value, $b.Value, $c.Value | ForEach-Object {
171+
Write-Output $PSItem
172+
}
173+
```
174+
175+
The output of this script is:
176+
177+
```powershell
178+
9
179+
9
180+
3
181+
9
182+
```
183+
184+
The above script:
185+
186+
- Creates an integer `$x` variable and assigns `1` to it.
187+
- Creates pointers `$a` and `$c` of `[ref]` types and points them at `$x`.
188+
- Creates pointer `$b` of `[PSReference]` type and points it, not at `$x`, but
189+
a copy thereof, because PowerShell treats `[ref]` and `[PSReference]`
190+
differently.
191+
- Adds 4 to `$x`, 3 to `$a`'s value, 2 to `$b`'s value, and 1 to `$a`'s value.
192+
193+
In the script above, `$x`, `$a.Value`, and `$c.Value` point to the same memory
194+
location. They are the same, i.e., 1 + 4 + 3 + 1 = 9. But `$b.Value` refers to
195+
a copy of `$x` at the time of its creation. Hence, it contains 1 + 2 = 3.
196+
150197
## See also
151198

152199
- [about_Variables](about_Variables.md)
153200
- [about_Environment_Variables](about_Environment_Variables.md)
154201
- [about_Functions](about_Functions.md)
155202
- [about_Script_Blocks](about_Script_Blocks.md)
156203
- [about_Scopes](about_scopes.md)
204+
- [about_Type_accelerators]
205+
206+
[about_Type_accelerators]: about_Type_Accelerators.md
207+
208+
[1]: https://github.com/PowerShell/PowerShell/blob/master/src/System.Management.Automation/engine/parser/ast.cs#L7983
209+
[2]: https://github.com/PowerShell/PowerShell/blob/master/src/System.Management.Automation/engine/parser/Compiler.cs#L6121

‎reference/7.5/Microsoft.PowerShell.Core/About/about_Ref.md‎

Lines changed: 56 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -70,10 +70,10 @@ scope.
7070

7171
You can code your functions to take a parameter as a reference, regardless of
7272
the type of data passed. This requires that you specify the parameters type
73-
as `System.Management.Automation.PSReference`, or `[ref]`.
73+
as `[ref]`.
7474

75-
When using references, you must use the `Value` property of the
76-
`System.Management.Automation.PSReference` type to access your data.
75+
When using references, you must use the `Value` property of the `[ref]` type to
76+
access your data.
7777

7878
```powershell
7979
Function Test([ref]$data)
@@ -85,7 +85,7 @@ Function Test([ref]$data)
8585
To pass a variable to a parameter that expects a reference, you must type
8686
cast your variable as a reference.
8787

88-
> [!NOTE]
88+
> [!IMPORTANT]
8989
> The brackets and parenthesis are BOTH required.
9090
9191
```powershell
@@ -148,10 +148,62 @@ $i = 0;$iRef = 1
148148

149149
Only the reference type's variable was changed.
150150

151+
### Relationship between [ref] and System.Management.Automation.PSReference
152+
153+
`Ref` is both a type accelerator for `System.Management.Automation.PSReference`
154+
(see [about_Type_Accelerators] for details) and a reserved keyword that
155+
PowerShell [treats][2] [especially][1]. Hence, `ref` and `PSReference` are not
156+
equivalents. The following script demonstrates their difference:
157+
158+
```powershell
159+
$x = 1
160+
161+
$a = [ref] $x
162+
$b = [System.Management.Automation.PSReference] $x
163+
$c = [ref] $x
164+
165+
$x +=4
166+
$a.Value +=3
167+
$b.Value +=2
168+
$c.Value +=1
169+
170+
$x, $a.Value, $b.Value, $c.Value | ForEach-Object {
171+
Write-Output $PSItem
172+
}
173+
```
174+
175+
The output of this script is:
176+
177+
```powershell
178+
9
179+
9
180+
3
181+
9
182+
```
183+
184+
The above script:
185+
186+
- Creates an integer `$x` variable and assigns `1` to it.
187+
- Creates pointers `$a` and `$c` of `[ref]` types and points them at `$x`.
188+
- Creates pointer `$b` of `[PSReference]` type and points it, not at `$x`, but
189+
a copy thereof, because PowerShell treats `[ref]` and `[PSReference]`
190+
differently.
191+
- Adds 4 to `$x`, 3 to `$a`'s value, 2 to `$b`'s value, and 1 to `$a`'s value.
192+
193+
In the script above, `$x`, `$a.Value`, and `$c.Value` point to the same memory
194+
location. They are the same, i.e., 1 + 4 + 3 + 1 = 9. But `$b.Value` refers to
195+
a copy of `$x` at the time of its creation. Hence, it contains 1 + 2 = 3.
196+
151197
## See also
152198

153199
- [about_Variables](about_Variables.md)
154200
- [about_Environment_Variables](about_Environment_Variables.md)
155201
- [about_Functions](about_Functions.md)
156202
- [about_Script_Blocks](about_Script_Blocks.md)
157203
- [about_Scopes](about_scopes.md)
204+
- [about_Type_accelerators]
205+
206+
[about_Type_accelerators]: about_Type_Accelerators.md
207+
208+
[1]: https://github.com/PowerShell/PowerShell/blob/master/src/System.Management.Automation/engine/parser/ast.cs#L7983
209+
[2]: https://github.com/PowerShell/PowerShell/blob/master/src/System.Management.Automation/engine/parser/Compiler.cs#L6121

0 commit comments

Comments
 (0)