联合体 Union ​

核心概念 ​

union 是 Rust 中的一种复合类型,与 struct 类似,但所有字段共享同一块内存空间。union 的大小等于其最大字段的大小(加上对齐填充),而不是所有字段大小之和。在任意时刻,union 只能存储一个字段的值,写入某个字段后再读取另一个字段会把同一块内存按不同类型解释——这就是类型双关(type punning)。正因为编译器无法追踪 union 当前存储的是哪个字段,读取 union 的字段需要在 unsafe 块中进行。

union 在 Rust 中主要用于 FFI(与 C 的 union 对应)和底层内存操作。

rust
// 定义一个 union
union IntOrFloat {
    i: i32,
    f: f32,
}

fn main() {
    // 创建 union,指定一个字段
    let u = IntOrFloat { i: 42 };

    // 读取 union 字段需要 unsafe
    // SAFETY: 我们刚写入了 i 字段
    unsafe {
        println!("i: {}", u.i);
    }

    // 写入另一个字段
    let u = IntOrFloat { f: 3.14 };

    // SAFETY: 我们刚写入了 f 字段
    unsafe {
        println!("f: {}", u.f);
    }

    // 类型双关:把 f32 的位模式当 i32 读
    // SAFETY: i32 和 f32 大小相同,读取不会越界
    // 但得到的值是 f32 的 IEEE 754 位表示
    unsafe {
        println!("f32 的位模式作为 i32: 0x{:08X}", u.i);
    }
}

union 与 struct 的区别 ​

rust
// struct:每个字段有独立的内存空间
struct PointStruct {
    x: f32,  // 偏移 0
    y: f32,  // 偏移 4
}
// 大小 = 8 字节

// union:所有字段共享内存空间
union PointUnion {
    x: f32,  // 偏移 0
    y: f32,  // 偏移 0(同一位置)
    xy: [f32; 2],  // 偏移 0
}
// 大小 = max(4, 4, 8) = 8 字节

fn main() {
    println!("struct 大小: {} 字节", std::mem::size_of::<PointStruct>());
    println!("union 大小:  {} 字节", std::mem::size_of::<PointUnion>());

    // struct 可以同时访问所有字段
    let ps = PointStruct { x: 1.0, y: 2.0 };
    println!("struct: x={}, y={}", ps.x, ps.y);

    // union 同一时刻只有一个字段有意义
    let pu = PointUnion { xy: [1.0, 2.0] };
    // SAFETY: xy 是刚写入的字段
    unsafe {
        println!("union xy: {:?}", pu.xy);
        // 读取 x 和 y 会得到 xy 数组的前4字节和前4字节(都是同一位置)
        println!("union x: {}", pu.x);  // 1.0(xy[0] 的位模式)
    }
}
特性structunion
内存布局字段独立存储字段共享内存
大小所有字段之和(+对齐)最大字段的大小
同时有效字段所有字段只有一个
读取字段安全需要 unsafe
写入字段安全安全(写入时)
Drop自动调用不自动调用
字段类型限制无字段必须是 Copy 或 ManuallyDrop

union 的字段限制 ​

rust
use std::mem::ManuallyDrop;

// union 的字段必须是 Copy 类型
// 或者用 ManuallyDrop 包装
union StringOrInt {
    // String 不是 Copy,需要用 ManuallyDrop
    s: ManuallyDrop<String>,
    i: i64,
}

// 纯 Copy 类型的 union
union NumberUnion {
    byte: u8,
    short: u16,
    int: u32,
    long: u64,
    float: f32,
    double: f64,
}

fn main() {
    // Copy 类型的 union 使用简单
    let num = NumberUnion { int: 0x41424344 };
    // SAFETY: 合法的类型双关
    unsafe {
        println!("int:   0x{:08X}", num.int);
        println!("short: 0x{:04X}", num.short);  // 低16位
        println!("byte:  0x{:02X}", num.byte);    // 低8位
    }

    // 包含非 Copy 类型的 union
    let u = StringOrInt {
        s: ManuallyDrop::new(String::from("hello")),
    };

    // SAFETY: s 是刚写入的字段
    unsafe {
        println!("字符串: {}", &*u.s);
    }

    // 手动 drop String
    let mut u = u;
    // SAFETY: s 字段有效
    unsafe {
        ManuallyDrop::drop(&mut u.s);
    }

    // 大小和对齐
    println!("\nNumberUnion 大小: {} 字节", std::mem::size_of::<NumberUnion>());
    println!("NumberUnion 对齐: {} 字节", std::mem::align_of::<NumberUnion>());
}

union 与 repr(C) ​

rust
// #[repr(C)] 保证 union 的内存布局与 C 兼容
// 在 FFI 中通常需要这个属性

#[repr(C)]
union CUnion {
    i: i32,
    f: f32,
    bytes: [u8; 4],
}

// 模拟 C 中的 sockaddr 联合体
#[repr(C)]
struct SockAddrIn {
    family: u16,
    port: u16,
    addr: u32,
}

#[repr(C)]
struct SockAddrIn6 {
    family: u16,
    port: u16,
    flowinfo: u32,
    addr: [u8; 16],
}

#[repr(C)]
union SockAddr {
    v4: SockAddrIn,
    v6: SockAddrIn6,
}

fn main() {
    // C 兼容的 union
    let u = CUnion { i: 0x41424344 };
    // SAFETY: 类型双关,查看 i32 的各字节
    unsafe {
        println!("i: 0x{:08X}", u.i);
        println!("f: {}", u.f);
        println!("bytes: {:?}", u.bytes);
    }

    // 模拟网络地址
    let addr = SockAddr {
        v4: SockAddrIn {
            family: 2,     // AF_INET
            port: 8080,
            addr: 0x7F000001,  // 127.0.0.1
        },
    };

    // SAFETY: 我们写入的是 v4
    unsafe {
        println!("\n网络地址:");
        println!("  family: {}", addr.v4.family);
        println!("  port: {}", addr.v4.port);
        println!("  addr: 0x{:08X}", addr.v4.addr);
    }

    println!("\nCUnion 大小: {} 字节", std::mem::size_of::<CUnion>());
    println!("SockAddr 大小: {} 字节", std::mem::size_of::<SockAddr>());
}

基本示例 ​

用 union 实现一个带标签的值类型(tagged union 的手动版本):

rust
use std::fmt;
use std::mem::ManuallyDrop;

// 值类型标签
#[derive(Debug, Clone, Copy, PartialEq)]
enum ValueTag {
    Int,
    Float,
    Bool,
    Str,
}

// union 存储实际数据
union ValueData {
    int: i64,
    float: f64,
    boolean: bool,
    string: ManuallyDrop<String>,
}

// 带标签的值:标签 + union
struct TaggedValue {
    tag: ValueTag,
    data: ValueData,
}

impl TaggedValue {
    fn from_int(v: i64) -> Self {
        TaggedValue { tag: ValueTag::Int, data: ValueData { int: v } }
    }

    fn from_float(v: f64) -> Self {
        TaggedValue { tag: ValueTag::Float, data: ValueData { float: v } }
    }

    fn from_bool(v: bool) -> Self {
        TaggedValue { tag: ValueTag::Bool, data: ValueData { boolean: v } }
    }

    fn from_str(v: &str) -> Self {
        TaggedValue {
            tag: ValueTag::Str,
            data: ValueData { string: ManuallyDrop::new(v.to_string()) },
        }
    }

    fn as_int(&self) -> Option<i64> {
        if self.tag == ValueTag::Int {
            // SAFETY: tag 为 Int,int 字段有效
            Some(unsafe { self.data.int })
        } else {
            None
        }
    }

    fn as_float(&self) -> Option<f64> {
        if self.tag == ValueTag::Float {
            // SAFETY: tag 为 Float,float 字段有效
            Some(unsafe { self.data.float })
        } else {
            None
        }
    }

    fn as_bool(&self) -> Option<bool> {
        if self.tag == ValueTag::Bool {
            // SAFETY: tag 为 Bool,boolean 字段有效
            Some(unsafe { self.data.boolean })
        } else {
            None
        }
    }

    fn as_str(&self) -> Option<&str> {
        if self.tag == ValueTag::Str {
            // SAFETY: tag 为 Str,string 字段有效
            Some(unsafe { &self.data.string })
        } else {
            None
        }
    }
}

impl fmt::Display for TaggedValue {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match self.tag {
            ValueTag::Int => write!(f, "{}", self.as_int().unwrap()),
            ValueTag::Float => write!(f, "{}", self.as_float().unwrap()),
            ValueTag::Bool => write!(f, "{}", self.as_bool().unwrap()),
            ValueTag::Str => write!(f, "\"{}\"", self.as_str().unwrap()),
        }
    }
}

impl Drop for TaggedValue {
    fn drop(&mut self) {
        // 只有 Str 类型需要手动 drop
        if self.tag == ValueTag::Str {
            // SAFETY: tag 为 Str,string 字段有效
            unsafe {
                ManuallyDrop::drop(&mut self.data.string);
            }
        }
    }
}

impl Clone for TaggedValue {
    fn clone(&self) -> Self {
        match self.tag {
            ValueTag::Int => Self::from_int(self.as_int().unwrap()),
            ValueTag::Float => Self::from_float(self.as_float().unwrap()),
            ValueTag::Bool => Self::from_bool(self.as_bool().unwrap()),
            ValueTag::Str => Self::from_str(self.as_str().unwrap()),
        }
    }
}

fn main() {
    // 创建不同类型的值
    let values = vec![
        TaggedValue::from_int(42),
        TaggedValue::from_float(3.14),
        TaggedValue::from_bool(true),
        TaggedValue::from_str("hello"),
        TaggedValue::from_int(-100),
    ];

    println!("=== 所有值 ===");
    for (i, v) in values.iter().enumerate() {
        println!("  [{}] {:?} = {}", i, v.tag, v);
    }

    // 类型检查和读取
    println!("\n=== 类型检查 ===");
    for v in &values {
        if let Some(n) = v.as_int() {
            println!("  整数: {}", n);
        } else if let Some(f) = v.as_float() {
            println!("  浮点: {}", f);
        } else if let Some(b) = v.as_bool() {
            println!("  布尔: {}", b);
        } else if let Some(s) = v.as_str() {
            println!("  字符串: {}", s);
        }
    }

    // 大小比较
    println!("\n=== 内存效率 ===");
    println!("ValueData union: {} 字节", std::mem::size_of::<ValueData>());
    println!("TaggedValue 总计: {} 字节", std::mem::size_of::<TaggedValue>());

    // 与 Rust enum 对比
    // Rust 的 enum 就是编译器管理的 tagged union
    // 上面的手动实现等价于:
    enum RustValue {
        Int(i64),
        Float(f64),
        Bool(bool),
        Str(String),
    }
    println!("Rust enum: {} 字节", std::mem::size_of::<RustValue>());
    println!("(Rust enum 是编译器管理的 tagged union,更安全)");
}

常见问题 ​

问题一:Rust 的 enum 和 union 有什么区别?

Rust 的 enum 本质上是编译器管理的 tagged union——编译器自动追踪当前是哪个变体,match 时保证类型安全。union 需要程序员手动追踪当前存储的是哪个字段,读取时需要 unsafe。大多数场景应优先使用 enum。

问题二:union 的字段为什么必须是 Copy 或 ManuallyDrop?

因为 union 不会自动调用 Drop。如果字段是非 Copy 的(如 String),销毁 union 时编译器不知道该 drop 哪个字段。ManuallyDrop 让程序员自己控制何时 drop。

问题三:写入 union 字段需要 unsafe 吗?

不需要。写入 union 字段是安全操作(只是把值写到那块内存中)。读取才需要 unsafe,因为编译器不知道当前存储的是哪个字段。

问题四:union 在 Rust 中的实际用途是什么?

主要用于 FFI(与 C 的 union 对应)和底层位操作(类型双关)。日常 Rust 编程中应使用 enum 代替 union。

适用场景 ​

  • FFI:与 C 库交互时匹配 C 的 union 类型
  • 类型双关:将同一块内存按不同类型解释
  • 内存优化:在嵌入式等资源受限环境中节省内存
  • 底层协议解析:网络协议、文件格式中的变长数据

注意事项 ​

  • 读取 union 字段需要 unsafe
  • 写入 union 字段不需要 unsafe
  • 字段必须是 Copy 类型或包装在 ManuallyDrop 中
  • union 不会自动调用 Drop,需要手动管理
  • FFI 中使用时应加 #[repr(C)]
  • 优先使用 Rust 的 enum(安全的 tagged union)

总结 ​

union 是所有字段共享同一块内存的复合类型,大小等于最大字段的大小。同一时刻只有一个字段有意义,读取字段需要 unsafe(编译器不追踪当前活跃字段)。字段必须是 Copy 类型或用 ManuallyDrop 包装,因为 union 不自动调用 Drop。union 主要用于 FFI(匹配 C 的 union)和底层类型双关操作。FFI 中应使用 #[repr(C)] 保证布局兼容。日常 Rust 编程应优先使用 enum——它是编译器管理的安全 tagged union,提供模式匹配和自动 Drop。