重复模式
核心概念
重复模式是声明宏中处理可变数量参数的机制。通过 $( ... ),* 或 $( ... ),+ 语法,宏可以匹配并展开零个或多个(*)、一个或多个(+)重复的语法片段。这是 macro_rules! 最强大的特性之一,标准库中的 vec!、println! 等宏都依赖重复模式来接受不定数量的参数。
重复模式的一般形式是 $( 内容 ) 分隔符 重复操作符,其中分隔符是可选的(通常是逗号 , 或分号 ;),重复操作符是 *(零或多次)或 +(一或多次)。在转写器中,用同样的 $( ... )* 或 $( ... )+ 来展开重复捕获的内容。
// $( ... ),* 匹配零个或多个逗号分隔的表达式
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
}重复操作符
// === * (零或多次) ===
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 | 无限 |
? | 零或一次 | 0 | 1 |
分隔符
// 分隔符是重复元素之间的 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);
}嵌套重复
// 重复模式可以嵌套
// 外层重复组,每组内含多个元素
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));
}重复中的多个变量
// 同一个重复模式中可以捕获多个变量
// 展开时它们必须在同一个 $( ... )* 块中
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);
}基本示例
// 实战:用重复模式实现常用工具宏
// 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! 一样接受任意数量的参数。