Skip to content

Commit 39efeec

Browse files
Update Unbox examples (#8034)
1 parent 4499e57 commit 39efeec

File tree

1 file changed

+15
-2
lines changed

1 file changed

+15
-2
lines changed

xml/System.Runtime.CompilerServices/Unsafe.xml

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1636,16 +1636,29 @@ The `Unbox<T>` method is simply a wrapper for the IL [unbox](xref:System.Reflect
16361636
The `Unbox<T>` method has an important usage constraint that is not enforced by language compilers and that is the responsibility of the caller. The IL `unbox` instruction returns a controlled-mutability managed pointer. Because .NET and .NET language compilers cannot represent this constraint, the `Unbox<T>` method returns a normal mutable `ref T`. However developers **must not** mutate the returned reference unless they are certain that `T` is a mutable struct type. For example, because the numeric primitives such as <xref:System.Int32> are not mutable struct types, the following code is not suppported:
16371637
16381638
```csharp
1639+
// The following line is NOT SUPPORTED.
16391640
Unsafe.Unbox<int>(obj) = 30;
16401641
```
16411642
1642-
In contrast, a type such as <xref:System.Drawing.Point?<displayProperty=nameWithType> is a mutable struct with public property setters, so the following code is supported:
1643+
In contrast, a type such as <xref:System.Drawing.Point?<displayProperty=nameWithType> is a mutable struct with public property setters, so mutating the boxed value by calling the property setters is supported:
16431644
16441645
```csharp
1646+
// The following lines are legal and supported.
16451647
Unsafe.Unbox<System.Drawing.Point>(obj).X = 50;
1648+
Unsafe.Unbox<System.Drawing.Point>(obj).Y = 70;
16461649
```
16471650
1648-
For more information, see sections III.1.8.1.2.2 ("Controlled-muttability managed pointers") and III.4.32 ("unbox -- convert boxed value type to its raw form") in [ECMA-335: Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/).
1651+
However, replacing the entire reference wholesale is not supported, even if the reference is to a mutable struct type.
1652+
1653+
```csharp
1654+
// Resetting the reference to default(T) is NOT SUPPORTED.
1655+
Unsafe.Unbox<System.Drawing.Point>(obj) = default(System.Drawing.Point);
1656+
1657+
// Setting the reference to a completely new value is NOT SUPPORTED.
1658+
Unsafe.Unbox<System.Drawing.Point>(obj) = new System.Drawing.Point(50, 70);
1659+
```
1660+
1661+
For more information, including detailed discussion of the usage constraints of this instruction, see sections III.1.8.1.2.2 ("Controlled-mutability managed pointers") and III.4.32 ("unbox -- convert boxed value type to its raw form") in [ECMA-335: Common Language Infrastructure (CLI)](https://www.ecma-international.org/publications-and-standards/standards/ecma-335/).
16491662
16501663
]]></format>
16511664
</remarks>

0 commit comments

Comments
 (0)