> ## Documentation Index > Fetch the complete documentation index at: https://docs.syntblaze.com/llms.txt > Use this file to discover all available pages before exploring further. # Rust Union A union in Rust is a user-defined composite type where all declared fields share the same underlying memory allocation. The size of a union is determined by its largest field, plus any necessary padding required to satisfy alignment constraints. Because the compiler cannot track which field (or "variant") was last written to, reading from a union bypasses Rust's standard type safety guarantees and is an inherently `unsafe` operation. ## Declaration Unions are declared using the `union` keyword, followed by a set of named and typed fields. The syntax is identical to that of a standard C-style struct. ```rust theme={"dark"} union IntOrFloat { i: u32, f: f32, } ``` ## Instantiation To instantiate a union, you must specify exactly one field to initialize. This establishes the initial bit pattern in the shared memory space. ```rust theme={"dark"} let mut u = IntOrFloat { f: 3.14 }; ``` ## Memory Layout Unlike an `enum` (which includes a hidden discriminant tag to track the active variant at runtime), a `union` contains no metadata. If a union contains a `u8` (1 byte) and a `u64` (8 bytes), the total size of the union will be 8 bytes, aligned to the 8-byte boundary. Writing to the `u8` field will only overwrite the first byte of the 8-byte allocation, leaving the remaining 7 bytes in an indeterminate state based on whatever was previously stored there. ## Field Access and Safety Writing to a union field is generally safe, as it merely overwrites the bits in the shared memory location. However, reading from a union field requires an `unsafe` block. The compiler relies entirely on the developer to ensure that the memory is being interpreted as the correct type. ```rust theme={"dark"} let mut u = IntOrFloat { i: 42 }; // Writing is safe u.f = 2.718; // Reading is unsafe; the programmer asserts the memory contains a valid f32 let float_val = unsafe { u.f }; ``` Interpreting the memory as the wrong type (e.g., reading the `f32` field when a `u32` was written) does not cause a compilation error. Instead, it results in a bit-cast, which may produce garbage data or trigger undefined behavior if the bit pattern is invalid for the target type (such as an invalid `bool` or `char`). ## Pattern Matching You can use pattern matching to extract values from a union. A union pattern can only specify exactly one field per pattern. Because matching on a union field is equivalent to reading it, the destructuring must occur within an `unsafe` block. Rust strictly enforces that **union patterns must be irrefutable**. You cannot use a refutable pattern to match a specific value directly in the union pattern (e.g., `IntOrFloat { i: 42 }` will be rejected by the compiler). Instead, you must bind the field to a variable. While you can create a multi-arm `match` statement using match guards, this introduces significant risk. Because union patterns are irrefutable, multi-arm matches are only possible if the preceding arms use guards (e.g., `IntOrFloat { i } if i == 0 => ...`). Match guards evaluate sequentially, meaning a guard will read the field's memory to evaluate the condition. If the underlying bit pattern is invalid for the type being evaluated in the guard, this sequential read will trigger undefined behavior before the correct arm is ever reached. ```rust theme={"dark"} let u = IntOrFloat { i: 42 }; unsafe { // Destructuring a single field using an irrefutable let binding let IntOrFloat { i } = u; println!("Integer value: {}", i); // Single-arm match with an irrefutable pattern match u { IntOrFloat { i: matched_val } => println!("Matched: {}", matched_val), } } ``` ## Drop Behavior and Non-Copy Types By default, unions work seamlessly with types that implement the `Copy` trait. Because the compiler does not know which field is currently active, it cannot safely determine which destructor to run when the union goes out of scope. To prevent undefined behavior during destruction, Rust requires that **any non-`Copy` type** (regardless of whether it explicitly implements `Drop` or not) must be wrapped in `std::mem::ManuallyDrop` to be placed in a union. This explicitly disables automatic cleanup, forcing the developer to manually drop the inner value using `unsafe` code before the union is destroyed. ```rust theme={"dark"} use std::mem::ManuallyDrop; union StringOrInt { s: ManuallyDrop, i: i32, } let mut u = StringOrInt { s: ManuallyDrop::new(String::from("Hello")) }; // The developer is strictly responsible for dropping the allocated memory unsafe { ManuallyDrop::drop(&mut u.s); } ```
Tired of Poor Rust Skills? Fix That With Deep Grasping! Learn More