元组结构体 ​

核心概念 ​

元组结构体(Tuple Struct)是一种没有字段名的结构体,字段通过位置索引访问。它结合了元组的简洁和结构体的类型区分——两个字段类型相同的元组结构体是不同的类型,不能互相赋值。元组结构体适合用于给元组赋予语义名称,或者创建新类型(Newtype Pattern)。

rust
// 定义元组结构体:没有字段名,只有类型
struct Color(u8, u8, u8);
struct Point(f64, f64, f64);

fn main() {
    let red = Color(255, 0, 0);
    let origin = Point(0.0, 0.0, 0.0);

    // 通过索引访问字段
    println!("R={}, G={}, B={}", red.0, red.1, red.2);
    println!("x={}, y={}, z={}", origin.0, origin.1, origin.2);

    // Color 和 Point 是不同的类型,即使字段数量和类型布局类似
    // let wrong: Color = origin;  // 编译错误:类型不匹配
}

与普通元组的区别 ​

rust
// 普通元组:没有类型名
let rgb: (u8, u8, u8) = (255, 128, 0);
let point: (f64, f64) = (3.0, 4.0);

// 两个结构相同的普通元组是同一类型
let a: (u8, u8, u8) = (1, 2, 3);
let b: (u8, u8, u8) = (4, 5, 6);
// a 和 b 类型相同,可以互相赋值

// 元组结构体:有类型名
struct Color(u8, u8, u8);
struct Velocity(u8, u8, u8);

fn main() {
    let c = Color(1, 2, 3);
    let v = Velocity(4, 5, 6);
    // c 和 v 是不同类型,即使内部结构完全相同
    // let wrong: Color = v;  // 编译错误
}
特性普通元组元组结构体
有类型名没有有
类型区分相同结构 = 相同类型不同名字 = 不同类型
访问方式.0, .1.0, .1
可以有方法不能可以(impl 块)
可以 derive不能可以

Newtype 模式 ​

当元组结构体只有一个字段时,叫做 Newtype(新类型)模式。它用来给现有类型创建一个语义上不同的新类型。

rust
// Newtype:只有一个字段的元组结构体
struct Meters(f64);
struct Seconds(f64);
struct Kilograms(f64);

impl Meters {
    fn new(value: f64) -> Self {
        Meters(value)
    }

    fn value(&self) -> f64 {
        self.0
    }
}

impl Seconds {
    fn new(value: f64) -> Self {
        Seconds(value)
    }

    fn value(&self) -> f64 {
        self.0
    }
}

// 类型安全:不能把米当成秒用
fn calculate_speed(distance: Meters, time: Seconds) -> f64 {
    distance.value() / time.value()
}

fn main() {
    let distance = Meters::new(100.0);
    let time = Seconds::new(9.58);

    let speed = calculate_speed(distance, time);
    println!("速度: {:.2} m/s", speed);

    // 类型安全保护
    // let wrong = calculate_speed(time, distance);  // 编译错误:参数类型不对
}

为元组结构体实现方法 ​

rust
#[derive(Debug, Clone, Copy, PartialEq)]
struct Vec2(f64, f64);

impl Vec2 {
    fn new(x: f64, y: f64) -> Self {
        Vec2(x, y)
    }

    fn zero() -> Self {
        Vec2(0.0, 0.0)
    }

    fn length(&self) -> f64 {
        (self.0 * self.0 + self.1 * self.1).sqrt()
    }

    fn normalize(&self) -> Self {
        let len = self.length();
        if len == 0.0 {
            Vec2::zero()
        } else {
            Vec2(self.0 / len, self.1 / len)
        }
    }

    fn add(&self, other: &Vec2) -> Vec2 {
        Vec2(self.0 + other.0, self.1 + other.1)
    }

    fn scale(&self, factor: f64) -> Vec2 {
        Vec2(self.0 * factor, self.1 * factor)
    }

    fn dot(&self, other: &Vec2) -> f64 {
        self.0 * other.0 + self.1 * other.1
    }
}

fn main() {
    let a = Vec2::new(3.0, 4.0);
    let b = Vec2::new(1.0, 2.0);

    println!("a = {:?}, 长度 = {:.2}", a, a.length());
    println!("b = {:?}, 长度 = {:.2}", b, b.length());
    println!("a + b = {:?}", a.add(&b));
    println!("a * 2 = {:?}", a.scale(2.0));
    println!("a . b = {:.2}", a.dot(&b));
    println!("a 归一化 = {:?}", a.normalize());
}

解构元组结构体 ​

rust
#[derive(Debug)]
struct Rgb(u8, u8, u8);

#[derive(Debug)]
struct Pair(String, i32);

fn main() {
    let color = Rgb(100, 200, 50);

    // let 解构
    let Rgb(r, g, b) = color;
    println!("r={}, g={}, b={}", r, g, b);

    // match 解构
    let pair = Pair(String::from("计数"), 42);
    match pair {
        Pair(ref name, value) if value > 0 => {
            println!("{} 是正数: {}", name, value);
        }
        Pair(ref name, value) => {
            println!("{} = {}", name, value);
        }
    }

    // 函数参数中解构
    let c = Rgb(255, 128, 0);
    print_rgb(c);
}

fn print_rgb(Rgb(r, g, b): Rgb) {
    println!("RGB: ({}, {}, {})", r, g, b);
}

基本示例 ​

用元组结构体和 Newtype 模式实现一个类型安全的单位转换系统:

rust
use std::fmt;

// 长度单位
#[derive(Debug, Clone, Copy)]
struct Millimeters(f64);

#[derive(Debug, Clone, Copy)]
struct Centimeters(f64);

#[derive(Debug, Clone, Copy)]
struct Meters(f64);

#[derive(Debug, Clone, Copy)]
struct Kilometers(f64);

// 实现 Display trait
impl fmt::Display for Millimeters {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{:.1}mm", self.0)
    }
}

impl fmt::Display for Centimeters {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{:.1}cm", self.0)
    }
}

impl fmt::Display for Meters {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{:.2}m", self.0)
    }
}

impl fmt::Display for Kilometers {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{:.3}km", self.0)
    }
}

// 类型之间的转换
impl From<Meters> for Centimeters {
    fn from(m: Meters) -> Self {
        Centimeters(m.0 * 100.0)
    }
}

impl From<Meters> for Millimeters {
    fn from(m: Meters) -> Self {
        Millimeters(m.0 * 1000.0)
    }
}

impl From<Meters> for Kilometers {
    fn from(m: Meters) -> Self {
        Kilometers(m.0 / 1000.0)
    }
}

impl From<Kilometers> for Meters {
    fn from(km: Kilometers) -> Self {
        Meters(km.0 * 1000.0)
    }
}

impl From<Centimeters> for Meters {
    fn from(cm: Centimeters) -> Self {
        Meters(cm.0 / 100.0)
    }
}

// 温度单位
#[derive(Debug, Clone, Copy)]
struct Celsius(f64);

#[derive(Debug, Clone, Copy)]
struct Fahrenheit(f64);

impl From<Celsius> for Fahrenheit {
    fn from(c: Celsius) -> Self {
        Fahrenheit(c.0 * 9.0 / 5.0 + 32.0)
    }
}

impl From<Fahrenheit> for Celsius {
    fn from(f: Fahrenheit) -> Self {
        Celsius((f.0 - 32.0) * 5.0 / 9.0)
    }
}

impl fmt::Display for Celsius {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{:.1}°C", self.0)
    }
}

impl fmt::Display for Fahrenheit {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{:.1}°F", self.0)
    }
}

fn main() {
    // 长度转换
    let height = Meters(1.75);
    let cm: Centimeters = height.into();
    let mm: Millimeters = height.into();
    let km: Kilometers = height.into();

    println!("身高: {} = {} = {} = {}", height, cm, mm, km);

    let marathon = Kilometers(42.195);
    let meters: Meters = marathon.into();
    println!("马拉松: {} = {}", marathon, meters);

    // 温度转换
    let boiling = Celsius(100.0);
    let f: Fahrenheit = boiling.into();
    println!("沸点: {} = {}", boiling, f);

    let body_temp = Fahrenheit(98.6);
    let c: Celsius = body_temp.into();
    println!("体温: {} = {}", body_temp, c);

    // 类型安全:不能混用不同单位
    // let wrong: Celsius = height.into();  // 编译错误
}

常见问题 ​

问题一:什么时候用元组结构体,什么时候用命名结构体?

字段含义明显且数量少(1-3个)时用元组结构体。字段多或者含义不直观时用命名结构体。Newtype 模式(单字段)是元组结构体最常见的用法。

问题二:元组结构体能有零个字段吗?

不能。零字段的是单元结构体(Unit Struct),写作 struct Marker;,不是元组结构体。

问题三:元组结构体可以用 derive 吗?

可以。元组结构体和命名结构体一样支持 #[derive(Debug, Clone, Copy, PartialEq)] 等 derive 宏,前提是所有字段类型都实现了对应的 trait。

问题四:Newtype 有运行时开销吗?

没有。Newtype 在编译后和原始类型完全一样,编译器会优化掉包装层。这是零成本抽象的一个典型例子。

适用场景 ​

  • Newtype 模式:给类型添加语义区分(米 vs 秒、用户ID vs 订单ID)
  • 简单的数据组合:颜色 RGB、二维坐标等字段含义明显的场景
  • 为外部类型实现 trait:用 Newtype 包装后可以为其实现自己的 trait
  • 类型安全:防止不同含义但相同底层类型的值混用

注意事项 ​

  • 元组结构体通过 .0、.1 等索引访问字段
  • 不同名字的元组结构体是不同类型,即使字段完全一样
  • Newtype(单字段元组结构体)是零成本抽象
  • 元组结构体支持 derive 宏
  • 元组结构体可以解构(let、match、函数参数)
  • 元组结构体也可以定义 impl 块添加方法
  • 字段多于3个时建议改用命名结构体

总结 ​

元组结构体是没有字段名的结构体,通过位置索引访问字段。它最大的价值在于类型区分——不同名字的元组结构体是不同的类型,即使内部结构完全相同。单字段的元组结构体构成 Newtype 模式,用于给现有类型赋予新的语义(如 Meters(f64) 和 Seconds(f64)),编译器会优化掉包装层,没有运行时开销。元组结构体适合字段含义明显且数量少的场景,字段多或含义不直观时应使用命名结构体。