From 5c5b65ddd136f82252bb862e2a42a237204df6d9 Mon Sep 17 00:00:00 2001 From: Jules Bertholet Date: Wed, 2 Sep 2026 17:23:30 -0400 Subject: [PATCH] Document which union patterns are unsafe --- src/items/unions.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/items/unions.md b/src/items/unions.md index 7b3d836e08..2f87c8af6f 100644 --- a/src/items/unions.md +++ b/src/items/unions.md @@ -124,6 +124,15 @@ fn f(u: MyUnion) { } ``` +`unsafe` is only required if the union field is accessed, in whole or in part, by the pattern, including any of its sub-patterns. For the purpose of this requirement, the following patterns are considered to perform an access: + +- [Literal patterns](../patterns.md#literal-patterns) +- [Identifier patterns](../patterns.md#identifier-patterns) +- [Range patterns](../patterns.md#range-patterns) +- [Reference patterns](../patterns.md#reference-patterns) +- [Struct](../patterns.md#struct-patterns) and [tuple struct](../patterns.md#tuple-struct-patterns) patterns which correspond to an enum variant +- [Path patterns](../patterns.md#path-patterns), if the result of expanding the constant into a pattern contains one of the above. + > [!WARNING] > The order in which the subpatterns of a pattern are tested is not specified. A union field named in a pattern may be read even when the pattern as a whole does not match. Reading a union field is undefined behavior unless it holds a valid value of its type (see [items.union.fields.validity]). Nothing else in the pattern can be relied on to prevent the read. >