Union 访问
核心概念
访问 union 的字段分为两种操作:写入和读取。写入 union 字段是安全的——你只是在向那块共享内存中存入一个值。读取 union 字段则需要 unsafe,因为编译器不追踪 union 当前存储的是哪个字段,读取错误的字段会把内存中的位模式按错误的类型解释,可能产生无效值(如无效的 bool 值、无效的引用等),导致未定义行为。程序员必须自己确保读取的字段就是最后写入的那个字段,或者确保这种类型双关(type punning)对当前的字段类型组合是安全的。
union Data {
int_val: i32,
float_val: f32,
bytes: [u8; 4],
}
fn main() {
// === 写入是安全的 ===
let mut data = Data { int_val: 42 };
// 切换到另一个字段(安全)
data.float_val = 3.14;
// === 读取需要 unsafe ===
// SAFETY: 刚写入了 float_val
unsafe {
println!("float: {}", data.float_val);
}
// 读取其他字段是类型双关
// SAFETY: i32 和 f32 大小相同,读取不会越界
// 但得到的值是 f32 3.14 的 IEEE 754 位表示
unsafe {
println!("int(类型双关): 0x{:08X}", data.int_val);
println!("bytes(类型双关): {:?}", data.bytes);
}
}字段写入
union Config {
as_u32: u32,
as_bits: ConfigBits,
}
#[derive(Clone, Copy)]
#[repr(C)]
struct ConfigBits {
enabled: u8,
mode: u8,
priority: u8,
flags: u8,
}
fn main() {
// 写入不需要 unsafe
let mut config = Config { as_u32: 0 };
// 通过不同字段写入
config.as_bits = ConfigBits {
enabled: 1,
mode: 2,
priority: 3,
flags: 0xFF,
};
// 每次写入都会覆盖整个 union 的内容
// 最后写入的字段决定了 union 当前的"活跃字段"
// SAFETY: 刚写入了 as_bits
unsafe {
println!("enabled: {}", config.as_bits.enabled);
println!("mode: {}", config.as_bits.mode);
// 通过 as_u32 查看整个 32 位值
println!("整体值: 0x{:08X}", config.as_u32);
}
// 重新写入 u32
config.as_u32 = 0x00030201;
// SAFETY: 刚写入了 as_u32,通过 as_bits 查看各字节
unsafe {
println!("\n写入 u32 后:");
println!("enabled: {}", config.as_bits.enabled); // 低字节
println!("mode: {}", config.as_bits.mode);
println!("priority: {}", config.as_bits.priority);
}
}字段读取
union Number {
signed: i32,
unsigned: u32,
float: f32,
bytes: [u8; 4],
}
fn main() {
// === 读取活跃字段 ===
let num = Number { signed: -1 };
// SAFETY: signed 是活跃字段
unsafe {
println!("signed: {}", num.signed);
}
// === 类型双关读取 ===
// -1 的补码表示是 0xFFFFFFFF
// SAFETY: i32 和 u32 大小相同
unsafe {
println!("unsigned(双关): {}", num.unsigned); // 4294967295
println!("bytes(双关): {:?}", num.bytes); // [255, 255, 255, 255]
}
// === 检查浮点数的位模式 ===
let num = Number { float: 1.0_f32 };
// SAFETY: 类型双关,查看 IEEE 754 表示
unsafe {
println!("\nf32 1.0:");
println!(" 位模式: 0x{:08X}", num.unsigned);
println!(" 字节: {:?}", num.bytes);
println!(" 符号位: {}", (num.unsigned >> 31) & 1);
println!(" 指数: {}", ((num.unsigned >> 23) & 0xFF) as i32 - 127);
println!(" 尾数: 0x{:06X}", num.unsigned & 0x7FFFFF);
}
// === 安全的替代方案 ===
// f32::to_bits() 和 f32::from_bits() 提供安全的类型双关
let bits = 1.0_f32.to_bits();
println!("\n安全替代: f32::to_bits() = 0x{:08X}", bits);
let back = f32::from_bits(bits);
println!("f32::from_bits() = {}", back);
}| 操作 | 需要 unsafe | 风险 |
|---|---|---|
| 写入活跃字段 | 否 | 无 |
| 写入其他字段(切换) | 否 | 旧数据被覆盖 |
| 读取活跃字段 | 是 | 低(只要确认活跃字段正确) |
| 类型双关读取 | 是 | 中(可能产生无效值) |
| 读取含引用/bool 的字段 | 是 | 高(可能产生 UB) |
模式匹配与 union
union Packet {
raw: u32,
header: PacketHeader,
}
#[derive(Clone, Copy)]
#[repr(C)]
struct PacketHeader {
packet_type: u8,
length: u8,
flags: u16,
}
fn process_packet(packet: &Packet) {
// union 不能直接用 match
// 需要先读取字段,然后对值进行 match
// SAFETY: 调用者保证 packet 已正确初始化
let header = unsafe { packet.header };
match header.packet_type {
0 => println!(" 心跳包, 长度: {}", header.length),
1 => println!(" 数据包, 长度: {}, flags: 0x{:04X}", header.length, header.flags),
2 => println!(" 控制包, flags: 0x{:04X}", header.flags),
_ => println!(" 未知类型: {}", header.packet_type),
}
}
fn main() {
// 构造数据包
let packets = [
Packet { header: PacketHeader { packet_type: 0, length: 0, flags: 0 } },
Packet { header: PacketHeader { packet_type: 1, length: 64, flags: 0x0001 } },
Packet { header: PacketHeader { packet_type: 2, length: 0, flags: 0x00FF } },
Packet { raw: 0xFF030200 }, // 通过原始值构造
];
println!("=== 处理数据包 ===");
for (i, packet) in packets.iter().enumerate() {
print!("包{}: ", i);
process_packet(packet);
// 查看原始值
// SAFETY: u32 类型双关总是安全的
unsafe {
println!(" 原始值: 0x{:08X}", packet.raw);
}
}
}带标签的安全封装
use std::mem::ManuallyDrop;
use std::fmt;
// 标签枚举
#[derive(Debug, Clone, Copy, PartialEq)]
enum JsonType {
Null,
Bool,
Int,
Float,
Str,
}
// 数据联合
union JsonData {
boolean: bool,
integer: i64,
float: f64,
string: ManuallyDrop<String>,
}
// 安全封装
struct JsonValue {
tag: JsonType,
data: JsonData,
}
impl JsonValue {
fn null() -> Self {
JsonValue { tag: JsonType::Null, data: JsonData { integer: 0 } }
}
fn from_bool(v: bool) -> Self {
JsonValue { tag: JsonType::Bool, data: JsonData { boolean: v } }
}
fn from_int(v: i64) -> Self {
JsonValue { tag: JsonType::Int, data: JsonData { integer: v } }
}
fn from_float(v: f64) -> Self {
JsonValue { tag: JsonType::Float, data: JsonData { float: v } }
}
fn from_string(v: String) -> Self {
JsonValue {
tag: JsonType::Str,
data: JsonData { string: ManuallyDrop::new(v) },
}
}
fn type_name(&self) -> &str {
match self.tag {
JsonType::Null => "null",
JsonType::Bool => "bool",
JsonType::Int => "int",
JsonType::Float => "float",
JsonType::Str => "string",
}
}
fn is_null(&self) -> bool { self.tag == JsonType::Null }
fn as_bool(&self) -> Option<bool> {
match self.tag {
JsonType::Bool => Some(unsafe { self.data.boolean }),
_ => None,
}
}
fn as_int(&self) -> Option<i64> {
match self.tag {
JsonType::Int => Some(unsafe { self.data.integer }),
_ => None,
}
}
fn as_float(&self) -> Option<f64> {
match self.tag {
JsonType::Float => Some(unsafe { self.data.float }),
_ => None,
}
}
fn as_str(&self) -> Option<&str> {
match self.tag {
JsonType::Str => Some(unsafe { &self.data.string }),
_ => None,
}
}
}
impl Drop for JsonValue {
fn drop(&mut self) {
if self.tag == JsonType::Str {
// SAFETY: tag 为 Str 时 string 字段有效
unsafe { ManuallyDrop::drop(&mut self.data.string); }
}
}
}
impl Clone for JsonValue {
fn clone(&self) -> Self {
match self.tag {
JsonType::Null => Self::null(),
JsonType::Bool => Self::from_bool(self.as_bool().unwrap()),
JsonType::Int => Self::from_int(self.as_int().unwrap()),
JsonType::Float => Self::from_float(self.as_float().unwrap()),
JsonType::Str => Self::from_string(self.as_str().unwrap().to_string()),
}
}
}
impl fmt::Display for JsonValue {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match self.tag {
JsonType::Null => write!(f, "null"),
JsonType::Bool => write!(f, "{}", self.as_bool().unwrap()),
JsonType::Int => write!(f, "{}", self.as_int().unwrap()),
JsonType::Float => write!(f, "{}", self.as_float().unwrap()),
JsonType::Str => write!(f, "\"{}\"", self.as_str().unwrap()),
}
}
}
fn main() {
let values = vec![
JsonValue::null(),
JsonValue::from_bool(true),
JsonValue::from_int(42),
JsonValue::from_float(3.14),
JsonValue::from_string("hello world".to_string()),
];
println!("=== JSON 值 ===");
for v in &values {
println!(" {} ({})", v, v.type_name());
}
// 类型检查
println!("\n=== 类型检查 ===");
let v = &values[3];
println!("is_null: {}", v.is_null());
println!("as_int: {:?}", v.as_int());
println!("as_float: {:?}", v.as_float());
// 克隆
let cloned = values[4].clone();
println!("\n克隆: {}", cloned);
// 内存效率
println!("\n=== 内存 ===");
println!("JsonData: {} 字节", std::mem::size_of::<JsonData>());
println!("JsonValue: {} 字节", std::mem::size_of::<JsonValue>());
}基本示例
用 union 实现网络协议的字节序转换和字段解析:
#[repr(C)]
union IpAddress {
addr32: u32,
octets: [u8; 4],
}
#[repr(C)]
#[derive(Clone, Copy)]
struct TcpHeader {
src_port: u16,
dst_port: u16,
seq_num: u32,
ack_num: u32,
data_offset_flags: u16,
window: u16,
checksum: u16,
urgent: u16,
}
#[repr(C)]
union HeaderView {
tcp: TcpHeader,
raw: [u8; 20],
}
impl IpAddress {
fn new(a: u8, b: u8, c: u8, d: u8) -> Self {
IpAddress { octets: [a, b, c, d] }
}
fn from_u32(addr: u32) -> Self {
IpAddress { addr32: addr }
}
fn to_string(&self) -> String {
// SAFETY: octets 始终可以安全读取(与 addr32 是同一块内存)
let o = unsafe { self.octets };
format!("{}.{}.{}.{}", o[0], o[1], o[2], o[3])
}
fn to_u32(&self) -> u32 {
// SAFETY: 类型双关,u32 和 [u8; 4] 大小相同
unsafe { self.addr32 }
}
fn is_loopback(&self) -> bool {
// SAFETY: octets 可以安全读取
unsafe { self.octets[0] == 127 }
}
fn is_private(&self) -> bool {
// SAFETY: octets 可以安全读取
let o = unsafe { self.octets };
o[0] == 10
|| (o[0] == 172 && (16..=31).contains(&o[1]))
|| (o[0] == 192 && o[1] == 168)
}
}
fn main() {
println!("=== IP 地址解析 ===");
let addrs = [
IpAddress::new(192, 168, 1, 100),
IpAddress::new(10, 0, 0, 1),
IpAddress::new(127, 0, 0, 1),
IpAddress::new(8, 8, 8, 8),
IpAddress::from_u32(0xC0A80164), // 192.168.1.100(大端序)
];
for addr in &addrs {
println!(" {} (0x{:08X}) 回环:{} 私有:{}",
addr.to_string(),
addr.to_u32(),
addr.is_loopback(),
addr.is_private());
}
// TCP 头部解析
println!("\n=== TCP 头部 ===");
let header = HeaderView {
tcp: TcpHeader {
src_port: 8080u16.to_be(),
dst_port: 443u16.to_be(),
seq_num: 12345u32.to_be(),
ack_num: 0,
data_offset_flags: 0x5000u16.to_be(), // 数据偏移=5(20字节)
window: 65535u16.to_be(),
checksum: 0,
urgent: 0,
},
};
// SAFETY: tcp 是活跃字段
unsafe {
println!("源端口: {}", u16::from_be(header.tcp.src_port));
println!("目标端口: {}", u16::from_be(header.tcp.dst_port));
println!("序列号: {}", u32::from_be(header.tcp.seq_num));
println!("窗口: {}", u16::from_be(header.tcp.window));
}
// 查看原始字节
// SAFETY: raw 和 tcp 共享内存
unsafe {
print!("原始字节: ");
for byte in &header.raw {
print!("{:02X} ", byte);
}
println!();
}
println!("\nHeaderView 大小: {} 字节", std::mem::size_of::<HeaderView>());
}常见问题
问题一:读取 union 的非活跃字段一定是 UB 吗?
不一定。如果两个字段的类型都是简单数值类型(如 i32 和 u32,或 i32 和 [u8; 4]),类型双关通常是安全的(所有位模式都是两种类型的有效值)。但如果涉及 bool(只有 0 和 1 有效)、引用(必须非空对齐)等类型,读取非活跃字段可能产生无效值,导致 UB。
问题二:union 的字段可以有不同大小吗?
可以。union 的大小等于最大字段的大小加上对齐填充。读取较小的字段只会读取共享内存的前几个字节。
问题三:如何安全地使用 union?
用一个外部标签(如枚举)追踪当前活跃的字段,封装在安全的 API 后面。这就是 Rust enum 的工作原理——编译器自动管理标签。
问题四:union 可以实现 trait 吗?
可以,但 impl 块中访问字段同样需要 unsafe。union 不能自动 derive 常见 trait(如 Debug、Clone),需要手动实现。
适用场景
- FFI:匹配 C 库中的 union 类型
- 协议解析:网络协议头部的字节级解析
- 类型双关:查看数值类型的位表示
- 硬件寄存器:通过不同视图访问寄存器位字段
注意事项
- 写入 union 字段不需要 unsafe,读取需要
- 读取非活跃字段是类型双关,需确保不产生无效值
- 涉及 bool、引用、枚举等类型的双关可能是 UB
- 用标签封装 union 以提供安全的 API
- union 不自动调用 Drop
- 优先使用 Rust enum 代替手动 tagged union
总结
Union 的字段访问分为写入(安全)和读取(unsafe)。写入时只是向共享内存存入值,编译器知道这是合法的。读取时编译器无法确定当前活跃字段,需要程序员在 unsafe 块中保证读取正确的字段。读取非活跃字段构成类型双关——对简单数值类型通常安全,但对 bool、引用等类型可能产生无效值导致 UB。实际项目中应用外部标签追踪活跃字段,将 union 封装在安全的 API 后面。Rust 的 enum 就是编译器管理的安全 tagged union,日常编程应优先使用 enum。