[Rust笔记] format! 宏使用心得-汇总

假期，我尝试使用rust做一款命令行工具，来磨砺自己的rust技术熟练度。起初，面对各式各样的字符串格式化功能点，我傻乎乎地尝试自己造轮子。但，实在是遇到了太多技术难点（可难死我了）。后来，通过在论坛发贴请教，我才了解到【标准库 - format!语法扩展】已经90%地满足了我的需求。至于，剩余10%的功能，可通过实现不同的format trait来深度定制-达成。

于是，我修改了假期目标为：

• 重新复习format!宏相关知识点。相比于之前（真是学过N遍了），我要提高对这块知识点的重视程度。在复习过程，做些归纳总结和条理清晰的笔记。

• 基于【标准库 - format!语法扩展】与【实现format trait深度定制】的手段，来做一款rust命令行工具。而不是，自己重新造轮子。

下面即是我对第一个目标的达成成果（除了丰富的教条总结归纳，还有30个例程） --- 掌握rust，先做“教条侠”。第二个目标还在进行中...

依赖关系宏观架构图

宏调用格式

format!("以{parameter}为占位符的·格式化字符串·字面量", arguments...)

• {parameter}名曰Formatting Argument

• argument名曰Value Argument

Formatting Argument格式

下文中的[...]结构表示

• 一对[与]之间的内容是可有可无的。

• 而且[...]结构是可多层嵌套的。

{[argument][:format-spec]}

• argument：【引用指令】表示如何找到Value Argument

• format-spec：【格式化指令】表示如何格式化Value Argument为字符串。

Formatting argument -> argument以如下三种形式引用Value Argument

• {} 名曰：Next (Value) Argument

  • 【顺序访问】不会受【随机访问】·跳跃式寻找Value Arguments的影响，因为前者维护了独立的【游标变量】来跟踪迭代位置。[例程1]

  • 顺序访问(Value) Argument，逐一遍历arguments列表中的每一项。但是，当format-spec内包含.*时，则会一次迭代遍历两项（下文有详细描述）。

  • Value Argument：无要求

• {positional parameter} 名曰：【索引】(Value) Argument

  • positional parameter是integer值。

  • 以始于0的索引值，随机访问(Value) Argument。

  • Value Argument：无要求

• {naming parameter} 名曰：【具名】(Value) Argument [例程2]

  • 要么，出现于Value Arguments列表的末端；格式：<parameter name>=<value>。

  • 要么，不出现在Value Arguments列表中。相反，编译器会

  • 在当前作用域内，

  • 寻找同名绑定变量，

  • 使用该绑定变量的值。（馁馁地逆天了）

  • naming parameter是identifier字符串。

  • 经由【参数名】，随机访问(Value) Argument。

  • Value Argument：

Formatting argument -> format-spec以如下五种形式进一步格式化Value Argument

下文中的[...]结构表示

• 一对[与]之间的内容是可有可无的。

• 而且[...]结构是可多层嵌套的。

• 字符串 - 宽度定制

  若mini-width与max-length同时指定，并且mini-width大于max-length，那么 [例程8]

  std::fmt::Display::to_string()成员方法将Value Argument序列化为字符串。

• 

  • padding-char名曰：“填充”

  • align名曰：“对齐”

    若对齐未生效（比如，对Debug trait实例），那就

  • mini-width名曰：“最小宽度”

  • max-length名曰：最多显示字符数（从左向右截取）[例程6]

  • 缺省。即，【空格】填充。

  • < 左 （默认）

  • ^ 中

  • > 右

  • 某个Value argument值

  • 或，当前作用域内，某个绑定变量的值

  • 要么，缺省。即，没有限制。

  • 要么，数字字面量；

  • 要么，$后缀【索引值】引用某个Value argument值 [例程4]

  • 要么，$后缀【具名变量】引用 [例程5]

  • 被格式化的值是后一个Value argument值

  • 而被格式化值前面（或左侧）的Value argument代表最多显示字符数

  • 某个Value argument值

  • 或，当前作用域内，某个绑定变量的值

  • 要么，缺省。即，显示全部字符。

  • 要么，数字字面量；

  • 要么，$后缀【索引值】引用某个Value argument值

  • 要么，$后缀【具名变量】引用

  • 要么，.*表示当前Formatting argument同时关联了两个Value argument [例程7]

  • {[<integer | identifier>][:[[[<padding-char>]<align>]<mini-width>][.<max-length>]]} [例程3]

1. 先使用max-length截断字符串

2. 再使用mini-width对截断后的字符串有填充与对齐处理

1. 先·普通格式化Value argument，

2. 再·对结果字符串做·对齐·格式化处理。

数字 - 宽度定制

就数字格式化而言，【正负号】与【进制符】都被计入总宽度内，并挤占了【占位符】的“坑位”。[例程16]

std::fmt::Display::to_string()成员方法将Value Argument序列化为字符串。

• padding-char名曰：填充

• align名曰：对齐

  若对齐未生效（比如，对Debug trait实例），那就

• sign名曰：正负号

• 0名曰：填充0数字

• mini-width名曰：最小宽度

• precision名曰：精度 [例程14]

• padding-char指定整个数字（含正负号）前后的填充符。

• padding-char填充符可以是任意字符。

• padding-char的填充优先级低于0 [例程10]

• 缺省。即，【空格】填充。

• 与sign后的0填充符作用不同，

• < 左

• ^ 中

• > 右 （默认）

• 要么，缺省。即，按需显示-号

• 要么，+。即，总是显示+/-号

• 0表示在【正负号】与【有效数字】之间以数字0加以填充`。

• 填充符号仅能是数字0

• 0填充优先级高于padding-char [例程11]

• 与padding-char填充符作用不同，

• 某个Value argument值

• 或，当前作用域内，某个绑定变量的值

• 要么，缺省。即，没有限制。

• 要么，数字字面量。

• 要么，$后缀【索引值】引用某个Value argument值 [例程12]

• 要么，$后缀【具名变量】引用 [例程13]

• 被格式化的值是后一个Value argument

• 而在被格式值前面（左侧）的Value argument代表精度

• 某个Value argument值

• 或，当前作用域内，某个绑定变量的值

• 要么，缺省。即，没有限制。

• 要么，数字字面量；

• 要么，$后缀【索引值】引用某个Value argument值

• 要么，$后缀【具名变量】引用

• 要么，.*表示当前Formatting argument同时关联了两个Value argument [例程15]

• {[<integer | identifier>][:[[[<padding-char>]<align>][<sign>][0]<mini-width>][.<precision>]]} [例程9]

1. 先·普通格式化Value argument，

2. 再·对结果字符串做·对齐·格式化处理。

数字 - 进制转换 + 有进制符前缀 + 宽度定制

就数字格式化而言，【正负号】与【进制符】都被计入总宽度内，并挤占了【占位符】的“坑位”。[例程22]

任何实现了Format trait的【自定义-数据类型】的实例都能被format-spec指令序列化与格式化。

标准库已经为基本数据类型提供了Format trait的默认实现。

• padding-char名曰：填充

• align名曰：对齐

  若对齐未生效（比如，对Debug trait实例），那就

• sign名曰：正负号

• #名曰：进制换算指令。

• 0名曰：填充0数字

• mini-width名曰：最小宽度

• numeration名曰：进制符

• 

• padding-char指定整个数字（含·正负号·与·进制符前缀0x, 0o, 0b·）前后的填充符。

• padding-char填充符可以是任意字符。

• padding-char的填充优先级低于#0 [例程18]

• 缺省。即，【空格】填充。

• 与#后0填充符的作用不同，

• < 左

• ^ 中

• > 右 （默认）

• 要么，缺省。按需显示-号

• 要么，+。即，总是显示正负号。

• 与末尾处的numeration参数配套出现。

• #0表示在【进制符前缀0x, 0o, 0b】与【有效数字】之间以数字0加以填充`。

• 填充符号仅能是数字0

• #0填充优先级高于padding-char [例程19]

• 与padding-char填充符作用不同，

• 某个Value argument值

• 或，当前作用域内，某个绑定变量的值

• 要么，缺省。即，没有限制。

• 要么，数字字面量。

• 要么，$后缀【索引值】引用某个Value argument值 [例程20]

• 要么，$后缀【具名变量】引用 [例程21]

• {[<integer | identifier>][:[[<padding-char>]<align>][<sign>]#[[0]<mini-width>]<numeration>]} [例程17]

1. 先·普通格式化Value argument，

2. 再·对结果字符串做·对齐·格式化处理。

数字 - 进制转换 + 无进制符前缀 + 宽度定制

就数字格式化而言，【正负号】与【进制符】都被计入总宽度内，并挤占了【占位符】的“坑位”。[例程27]

任何实现了Format trait的【自定义-数据类型】的实例都能被format-spec指令序列化与格式化。

标准库已经为基本数据类型提供了Format trait的默认实现。

• padding-char名曰：填充

• align名曰：对齐

  若对齐未生效（比如，对Debug trait实例），那就

• sign名曰：正负号

• 0名曰：填充0数字

• mini-width名曰：最小宽度

• numeration名曰：进制符

• 

• padding-char指定整个数字（含正负号）前后的填充符。

• padding-char填充符可以是任意字符。

• padding-char的填充优先级低于0 [例程23]

• 缺省。即，【空格】填充。

• 与sign后0填充符作用不同，

• < 左

• ^ 中

• > 右 （默认）

• 要么，缺省。按需显示-号

• 要么，+。即，总是显示正负号

• 0表示在【正负号】与【有效数字】之间以数字0加以填充。

• 填充符号仅能是数字0

• 0填充优先级高于padding-char [例程24]

• 与padding-char填充符作用不同，

• 某个Value argument值

• 或，当前作用域内，某个绑定变量的值

• 要么，缺省。即，没有限制。

• 要么，数字字面量。

• 要么，$后缀【索引值】引用某个Value argument值 [例程25]

• 要么，$后缀【具名变量】引用 [例程26]

• {[<integer | identifier>][:[[[<padding-char>]<align>][<sign>][[0]<mini-width>]]<numeration>]}

1. 先·普通格式化Value argument，

2. 再·对结果字符串做·对齐·格式化处理。

有缩进格式化

• 适用于复合数据结构。比如，Vec<T>和HashMap<K, V>。

• {[<integer | identifier>][:#?]} [例程28]

在·格式化字符串·字面量内，转义录入{与}字面量

• 转义{为{{

• 转义}为}}

Value argument两种语法错误形式

• Value argument未被任何Formatting Argument所引用

• 【索引】(Value) Argument或Next (Value) Argument出现于【具名】(Value) Argument之后。[例程29]

使format-spec格式化指令对自定义数据类型（的实例）起作用

技术手段就是给【自定义数据类型】实现各种Format trait，从std::fmt::Display与std::fmt::Debug到std::fmt::Octal等等一个都别落下。[例程30]

但是，有两个点值得一聊：

• Format trait默认实现已经帮助开发者完成了

  开发者仅需调用std::fmt::Formatter的成员方法（比如，std::fmt::Formatter::fill(&self)）就可获取格式化指令的具体值。

  • 对【格式化字符串·字面量】的解析处理

  • 和，对format-spec指令值的提取工作

• 虽然“抽象”成员方法fn fmt(...) -> std::fmt::Result的返回值类型是Result，但是fn fmt()不应该将format trait业务实现代码的“本地”错误伪装成std::fmt::Result返回。因为rust设计要求：

  • 字符串格式化自身是一个【无错】操作

  • std::fmt::Result仅被用来反映底层输出流遇到的硬件失败。

std::fmt::Display与std::fmt::Debug的区别

就功能来说，这两个trait都差不多。它们之间的差别之处都集中在语义上：

• std::fmt::Display表示一个类型实例能够由UTF-8字符串来描述。因为不是所有类型的实例都是可字符串描述的（只可意会，不可言传），所以不是所有的类型都需要实现该trait。

• std::fmt::Debug用于debugging目的，描述某个类型实例的内部数据状态。所以，理论上，所有的类型都应该实现该trait，以方便随时按需程序调试。

结束语

这次想和大家分享的内容就是这些。

－－－－－－－－－－－－－－－－－－－－－

另附上苦瓜小仔的一份思维导图：

清晰版请参阅：https://www.yuque.com/zhoujiping/programming/pygvaf?inner=sSp4s