You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: xml/System.Runtime.CompilerServices/Unsafe.xml
+15-2Lines changed: 15 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -1636,16 +1636,29 @@ The `Unbox<T>` method is simply a wrapper for the IL [unbox](xref:System.Reflect
1636
1636
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:
1637
1637
1638
1638
```csharp
1639
+
// The following line is NOT SUPPORTED.
1639
1640
Unsafe.Unbox<int>(obj) = 30;
1640
1641
```
1641
1642
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:
1643
1644
1644
1645
```csharp
1646
+
// The following lines are legal and supported.
1645
1647
Unsafe.Unbox<System.Drawing.Point>(obj).X = 50;
1648
+
Unsafe.Unbox<System.Drawing.Point>(obj).Y = 70;
1646
1649
```
1647
1650
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.
// 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/).
0 commit comments