重复模式 ​

核心概念 ​

重复模式是声明宏中处理可变数量参数的机制。通过 $( ... ),* 或 $( ... ),+ 语法,宏可以匹配并展开零个或多个(*)、一个或多个(+)重复的语法片段。这是 macro_rules! 最强大的特性之一,标准库中的 vec!、println! 等宏都依赖重复模式来接受不定数量的参数。

重复模式的一般形式是 $( 内容 ) 分隔符 重复操作符,其中分隔符是可选的(通常是逗号 , 或分号 ;),重复操作符是 *(零或多次)或 +(一或多次)。在转写器中,用同样的 $( ... )* 或 $( ... )+ 来展开重复捕获的内容。

rust
// $( ... ),* 匹配零个或多个逗号分隔的表达式
macro_rules! print_all {
    // $($e:expr),* 匹配零个或多个表达式
    ($($e:expr),*) => {
        // 在转写器中用同样的 $( ... )* 展开
        $(
            println!("{}", $e);
        )*
    };
}

// $( ... ),+ 匹配一个或多个
macro_rules! sum {
    ($first:expr $(, $rest:expr)*) => {{
        let mut total = $first;
        $(
            total += $rest;
        )*
        total
    }};
}

fn main() {
    print_all!();                    // 零个参数,什么都不打印
    print_all!(1);                   // 一个参数
    print_all!(1, "hello", true);    // 三个参数

    println!("sum = {}", sum!(1, 2, 3, 4, 5));  // 15
}

重复操作符 ​

rust
// === * (零或多次) ===
macro_rules! zero_or_more {
    ($($item:expr),*) => {
        println!("收到 {} 个参数", {
            let mut count = 0;
            $( let _ = $item; count += 1; )*
            count
        });
    };
}

// === + (一或多次) ===
macro_rules! one_or_more {
    ($($item:expr),+) => {
        println!("至少一个参数");
        $( println!("  - {}", $item); )+
    };
}

// === ? (零或一次,Rust 1.32+) ===
macro_rules! zero_or_one {
    ($mandatory:expr $(, $optional:expr)?) => {
        println!("必选: {}", $mandatory);
        $(
            println!("可选: {}", $optional);
        )?
    };
}

fn main() {
    zero_or_more!();           // 0 个
    zero_or_more!(1, 2, 3);   // 3 个

    one_or_more!(10);          // 至少 1 个
    one_or_more!(10, 20, 30); // 3 个
    // one_or_more!();         // 编译错误:至少需要一个

    zero_or_one!(42);          // 只有必选
    zero_or_one!(42, 99);     // 必选 + 可选
}
操作符含义最少次数最多次数
*零或多次0无限
+一或多次1无限
?零或一次01

分隔符 ​

rust
// 分隔符是重复元素之间的 token,放在 ) 和操作符之间

// 逗号分隔(最常见)
macro_rules! comma_sep {
    ($($e:expr),*) => {
        [$($e),*]
    };
}

// 分号分隔
macro_rules! semicolon_sep {
    ($($s:stmt);*) => {
        $($s;)*
    };
}

// 箭头分隔
macro_rules! arrow_sep {
    ($($from:expr => $to:expr),*) => {
        $(println!("{} → {}", $from, $to);)*
    };
}

// 无分隔符
macro_rules! no_sep {
    ($($t:tt)*) => {
        $(print!("{} ", stringify!($t));)*
        println!();
    };
}

// 尾随分隔符处理:$(,)? 允许最后一个元素后有可选的逗号
macro_rules! trailing_comma {
    ($($e:expr),* $(,)?) => {
        vec![$($e),*]
    };
}

fn main() {
    let arr = comma_sep![1, 2, 3, 4, 5];
    println!("{:?}", arr);

    semicolon_sep!(
        let a = 1;
        let b = 2;
        println!("a + b = {}", a + b)
    );

    arrow_sep!(1 => "one", 2 => "two", 3 => "three");

    no_sep!(hello world foo bar);

    // 尾随逗号:两种写法都合法
    let v1 = trailing_comma![1, 2, 3];
    let v2 = trailing_comma![1, 2, 3,];  // 有尾随逗号也行
    println!("{:?} {:?}", v1, v2);
}

嵌套重复 ​

rust
// 重复模式可以嵌套

// 外层重复组,每组内含多个元素
macro_rules! matrix {
    // 匹配 [1,2,3; 4,5,6; 7,8,9] 形式
    ($( [$($elem:expr),*] );* $(;)?) => {{
        let mut rows = Vec::new();
        $(
            let row = vec![$($elem),*];
            rows.push(row);
        )*
        rows
    }};
}

// 嵌套重复:为多个结构体实现多个方法
macro_rules! impl_methods {
    (
        $struct_name:ident;
        $(
            fn $method:ident($($arg:ident : $ty:ty),*) -> $ret:ty $body:block
        )*
    ) => {
        impl $struct_name {
            $(
                fn $method($($arg: $ty),*) -> $ret $body
            )*
        }
    };
}

#[derive(Debug)]
struct Calculator;

impl_methods! {
    Calculator;
    fn add(a: i32, b: i32) -> i32 { a + b }
    fn mul(a: i32, b: i32) -> i32 { a * b }
    fn neg(x: i32) -> i32 { -x }
}

fn main() {
    let m = matrix![
        [1, 2, 3];
        [4, 5, 6];
        [7, 8, 9]
    ];
    for row in &m {
        println!("{:?}", row);
    }

    println!("add: {}", Calculator::add(3, 4));
    println!("mul: {}", Calculator::mul(3, 4));
    println!("neg: {}", Calculator::neg(5));
}

重复中的多个变量 ​

rust
// 同一个重复模式中可以捕获多个变量
// 展开时它们必须在同一个 $( ... )* 块中

macro_rules! key_value {
    ($($key:expr => $value:expr),* $(,)?) => {{
        let mut map = std::collections::HashMap::new();
        $(
            // $key 和 $value 在同一个重复层级
            map.insert($key, $value);
        )*
        map
    }};
}

// 多变量配对使用
macro_rules! define_consts {
    ($($name:ident : $ty:ty = $val:expr);* $(;)?) => {
        $(
            const $name: $ty = $val;
        )*
    };
}

define_consts! {
    MAX_SIZE: usize = 1024;
    MIN_SIZE: usize = 1;
    DEFAULT_NAME: &str = "unnamed"
}

// 同一重复中的变量必须出现相同次数
macro_rules! pairs {
    ($($a:expr, $b:expr);*) => {
        vec![$(($a, $b)),*]
    };
}

fn main() {
    let map = key_value! {
        "name" => "Alice",
        "age" => "30",
        "city" => "Beijing",
    };
    println!("{:?}", map);

    println!("MAX_SIZE = {}", MAX_SIZE);
    println!("DEFAULT_NAME = {}", DEFAULT_NAME);

    let pairs = pairs!(1, "one"; 2, "two"; 3, "three");
    println!("{:?}", pairs);
}

基本示例 ​

rust
// 实战:用重复模式实现常用工具宏

// 1. 类似 vec! 的自定义集合初始化
macro_rules! btree_set {
    ($($elem:expr),* $(,)?) => {{
        let mut set = std::collections::BTreeSet::new();
        $( set.insert($elem); )*
        set
    }};
}

// 2. 格式化多行输出
macro_rules! multiline {
    ($($line:expr),* $(,)?) => {{
        let mut output = String::new();
        $(
            output.push_str(&format!("{}\n", $line));
        )*
        output
    }};
}

// 3. 批量实现 From trait
macro_rules! impl_from {
    ($target:ty; $($source:ty),+ $(,)?) => {
        $(
            impl From<$source> for $target {
                fn from(val: $source) -> Self {
                    val as $target
                }
            }
        )+
    };
}

// 为 f64 实现从多个整数类型的 From
impl_from!(f64; i8, i16, i32, u8, u16, u32);

// 4. 递归求最小值
macro_rules! min {
    ($x:expr) => { $x };
    ($x:expr, $($rest:expr),+) => {
        {
            let a = $x;
            let b = min!($($rest),+);
            if a < b { a } else { b }
        }
    };
}

// 5. 断言多个条件
macro_rules! assert_all {
    ($($cond:expr),+ $(,)?) => {
        $(
            assert!($cond, "断言失败: {}", stringify!($cond));
        )+
    };
}

fn main() {
    // BTreeSet
    let set = btree_set![3, 1, 4, 1, 5, 9, 2, 6];
    println!("BTreeSet: {:?}", set);

    // 多行
    let text = multiline!("第一行", "第二行", "第三行");
    print!("{}", text);

    // From
    let x: f64 = f64::from(42_i32);
    let y: f64 = f64::from(255_u8);
    println!("from i32: {}, from u8: {}", x, y);

    // 最小值
    println!("min: {}", min!(5, 3, 8, 1, 7));

    // 批量断言
    assert_all!(
        1 + 1 == 2,
        "hello".len() == 5,
        vec![1, 2, 3].len() == 3,
    );
    println!("所有断言通过");
}

常见问题 ​

问题一: 和 + 在实际使用中怎么选?*

如果宏允许"零个参数"的调用,用 *。如果至少需要一个参数,用 +。比如 vec![](空数组)需要用 *,而 println! 至少需要一个格式字符串,核心参数用 + 更合适。

问题二:为什么要加 $(,)? 处理尾随逗号?

Rust 社区习惯在列表最后一项后面加逗号(方便增删元素、减少 git diff),所以宏应该接受这种写法。$(,)? 表示"可选的尾随逗号",这是惯用做法。

问题三:重复中的多个变量必须出现相同次数吗?

是的。如果匹配器中 $a 和 $b 在同一个 $( ... )* 中捕获,那么在转写器中它们必须在同一个 $( ... )* 中展开,并且次数必须相同。不同重复层级的变量不能混用。

问题四:重复模式可以嵌套多少层?

没有硬性限制,但实际中很少超过两三层。嵌套太深会让宏的可读性和调试难度急剧增加。如果嵌套超过两层,可以考虑拆分成多个宏或改用过程宏。

适用场景 ​

  • 可变参数列表:接受不定数量的参数
  • 集合初始化:vec!、hash_map! 等初始化宏
  • 批量代码生成:为多个类型实现同一 trait
  • DSL 构建:重复的语法结构

注意事项 ​

  • * 匹配零或多次,+ 匹配一或多次,? 匹配零或一次
  • 分隔符只能是单个 token,不能是多 token 序列
  • 同一重复层级的变量必须在同一 $( ... )* 中展开
  • 用 $(,)? 处理尾随逗号是惯用写法
  • 嵌套重复不宜过深,影响可读性

总结 ​

重复模式是声明宏处理可变参数的核心机制。$( ... ),* 匹配零或多个逗号分隔的片段,$( ... ),+ 至少匹配一个,$( ... )? 匹配零或一个。分隔符可以是逗号、分号、箭头等任意单 token,也可以省略。转写器中用同样的 $( ... )* 展开捕获的重复内容。同一重复层级中的多个变量必须配对使用。嵌套重复可以处理二维结构(如矩阵)。$(,)? 是处理尾随逗号的标准做法。重复模式让宏能像 vec!、println! 一样接受任意数量的参数。