Rust 编程语言的标准函数库中的 std::fmt 模块提供了多种宏来格式化或是印出字符串。在这个章节中,我们将会学习 format!、write!、writeln!、print!、println!、eprint!、eprintln! 宏的详细使用方式。

先来看看以上提及的宏,它们的用途:

  • format!:可以将文字格式化成 String 结构实体。
  • write!:可以将格式化之后的文字输出到某个缓冲空间。
  • writeln!:可以将格式化之后的文字最后再多加一个换行字符输出到某个缓冲空间。
  • print!:可以将格式化之后的文字输出到标准输出(stdout)。
  • println!:可以将格式化之后的文字最后再多加一个换行字符输出到标准输出(stdout)。
  • eprint!:可以将格式化之后的文字输出到标准错误(stderr)。
  • eprintln!:可以将格式化之后的文字最后再多加一个换行字符输出到标准错误(stderr)。

格式化文字的用法

Rust 编程语言的标准函数库提供的文字格式化方式,是利用字符串定数来撰写文字格式化的范本(template),接着将字符串定数之后传入的参数代入至范本中由 {} 组成的空位,重新组合成新的字符串。编译器会在编译阶段的时候,就去编译文字格式化的范本,因此这样的使用方式对于程序运行阶段的运算资源负担并不大。

文字格式化的范例如下:

format!("Hello");                                     // => "Hello"
format!("Hello, {}!", "world");                       // => "Hello, world!"
format!("The number is {}", 1);                       // => "The number is 1"
format!("{:?}", (3, 4));                              // => "(3, 4)"
format!("{1:?} {0:?}", (3, 4), (5, 6));               // => "(5, 6) (3, 4)"
format!("{value}", value = 4);                        // => "4"
format!("{value1} {value2}", value1 = 4, value2 = 5); // => "4 5"
format!("{name} {}", 1, name = "MagicLen");           // => "MagicLen 1"
format!("{} {}", 1, 2);                               // => "1 2"
format!("{0} {1}", 1, 2);                             // => "1 2"
format!("{1} {0}", 1, 2);                             // => "2 1"
format!("{1} {} {2} {} {0} {}", 1, 2, 3);             // => "2 1 3 2 1 3"
format!("{:4}", 42);                                  // => "  42" with leading spaces
format!("{:<4}", 42);                                 // => "42  " with trailing spaces
format!("{:04}", 42);                                 // => "0042" with leading zeros
format!("{:0<4}", 42);                                // => "4200" with trailing zeros
format!("{:+}", 42);                                  // => "+42"
format!("{:b}", 42);                                  // => "101010"
format!("{:#b}", 42);                                 // => "0b101010"
format!("{:.*}", 2, 1.2345);                          // => "1.23"
format!("{:.*}", 3, 1.2345);                          // => "1.234"
format!("{:.*}", 3, 1.2335);                          // => "1.234"
format!("{:.3}", 1.2335);                             // => "1.234"
format!("{:7.3}", 1.2335);                            // => "  1.234" with leading spaces
format!("{:<7.3}", 1.2335);                           // => "1.234  " with trailing spaces
format!("{:07.3}", 1.2335);                           // => "001.234" with leading zeros
format!("{:0>7.3}", 1.2335);                          // => "001.234" with leading zeros
format!("{:<07.3}", 1.2335);                          // => "001.234" with leading zeros
format!("{:0<7.3}", 1.2335);                          // => "1.23400" with trailing zeros
format!("{:07.3}", -1.2335);                          // => "-01.234" with leading zeros after the sign character
format!("{:0>7.3}", -1.2335);                         // => "0-1.234" with leading zeros before the sign character
format!("{:<07.3}", -1.2335);                         // => "-01.234" with leading zeros after the sign character
format!("{:0<7.3}", -1.2335);                         // => "-1.2340" with trailing zeros
format!("{:@>5}", "Hi");                              // => "@@@Hi" with leading '@'s
format!("{:@<5}", "Hi");                              // => "Hi@@@" with trailing '@'s
format!("{:@^5}", "Hi");                              // => "@Hi@@" with leading and trailing '@'s (center alignment)
format!("{3:.2$} {1:.0$}", 2, 1.2345, 1, 1.2345);     // => "1.2 1.23"
format!("{second:.second_decimal$} {first:.first_decimal$}", first_decimal = 2, first = 1.2345, second_decimal = 1, second = 1.2345); // => "1.2 1.23"

几个比较特别需要注意的地方是,如果要同时使用一般依照位置来填入的参数和依照名称来填入的参数,依照名称来填入的参数必须要写在依照位置来填入的参数之后,否则会编译错误。例如以下程序会编译错误:

format!("{name} {}", name = "MagicLen", 1);

{} 类似 {0}、{1} 等用法,只是它不明确指定参数的位置,而是让编译器在编译阶段时,由其在范本中从左到右的顺序来推断它的参数位置。也就是说,{1} {} {2} {} {0} {} 会被视为 {1} {0} {2} {1} {0} {2}。如果 {} 内有冒号 : 的话,在 : 的左边可以指定一个可以在当前 scope 下访问的变量名称,或是参数明确的位置数字或是名称;在 : 的右边可以使用一些比较特别的格式化方式,格式如下:

:[[填充字符](>|<|^)][+|-][#][[0]宽度][.精准度][特性符号]

当格式化出来的文字宽度小于格式化方式所设置的 宽度,就会用 填充字符 来填充不足的部份,而填充的位置则是依照 >、< 或 ^ 来决定。> 表示要将字符填充到文字左边(原本的文字靠右对齐);< 表示要将字符填充到文字右边(原本的文字靠左对齐);^ 表示要将字符填充到文字两边(原本的文字置中对齐)。填充字符 预设的字符是空格 。至于预设对齐方式,不同类型有不同的预设对齐方式,举例来说,如果是数值的话为靠右对齐 >,如果是字符串的话则为靠左对齐 <。

+ 或 -,前者可以用来指定数值就算是正数也要将正号 + 写在文字中,而后者就比较不常用了。- 会被用到的地方可能是要将 Foo(负数) 这类的值在格式化的时候写成 -Foo(正数)。

# 可以用来显示更多的文字,有点像是第二种格式化的模式。

宽度 前可以加上 0,可以将数值开头的部份以字符 0 来填充,如果数值有正负号,字符 0 会被填充在正负号之后。

精准度 可以用来指定有小数的数值在格式化之后要显示几位小数。

宽度 和 精准度 可以读取参数中传入的 usize 类型的值,这个参数可以用位置数字或是名称来指定,且位置数字或名称写在范本中 宽度 和 精准度 的位置时,结尾需要加上 $ 字符。

特性符号 列表如下:

  • 无:使用 Display 特性的 fmt 方法。
  • ?:使用 Debug 特性的 fmt 方法。
  • x:使用 LowerHex 特性的 fmt 方法。
  • X:使用 UpperHex 特性的 fmt 方法。
  • x?:使用 Debug 特性的 fmt 方法,但其中的整数会以小写的十六进制来表示。
  • X?:使用 Debug 特性的 fmt 方法,但其中的整数会以大写的十六进制来表示。
  • o:使用 Octal 特性的 fmt 方法。
  • p:使用 Pointer 特性的 fmt 方法。
  • b:使用 Binary 特性的 fmt 方法。
  • e:使用 LowerExp 特性的 fmt 方法。
  • E:使用 UpperExp 特性的 fmt 方法。

如果在使用 x、X、x?、X?、o、b 特性符号时,有加上井字号 # 使用其第二种格式化模式的话,格式化出来的数值文字会分别以 0x、0o、0b 为开头。

而如果在使用 ? 特性符号时,有加上井字号 #,则会美化原先 Debug 特性格式化出来的文字。举例来说:

#[derive(Debug)]
struct Point {
    x: i32,
    y: i32,
}


fn main() {
    let origin = Point { x: 0, y: 0 };

    println!("{origin:?}");
}

不加上井字号 #,程序运行结果如下:

Point { x: 0, y: 0 }
#[derive(Debug)]
struct Point {
    x: i32,
    y: i32,
}


fn main() {
    let origin = Point { x: 0, y: 0 };

    println!("{origin:#?}");
}

加上井字号,程序运行结果如下:

Point {
    x: 0,
    y: 0,
}

范本中的空位皆是由 {} 组成,那如果我们真的需要在文字中使用到大括号 {} 要怎么办呢?那就只能用两个相同连续的大括号来表示一个大括号文字了,{{ 可以表示 {,}} 可以表示 }。例如:

fn main() {
    println!("{{}}");
}

程序运行结果如下:

{}

format!

fn main() {
    let mut hello = format!("{}, ", "Hello");
    hello.push_str("world.");
}

write!

use std::io::{self, Write};

fn main() {
    let mut w = Vec::new();

    write!(&mut w, "Hello {}!", "world").unwrap();
}
use std::io::{self, Write};

fn main() {
    let mut stdout = io::stdout();

    write!(&mut stdout, "Hello {}!", "world").unwrap();
}

writeln!

use std::io::{self, Write};

fn main() {
    let mut w = Vec::new();

    writeln!(&mut w, "Hello {}!", "world").unwrap();
}
use std::io::{self, Write};

fn main() {
    let mut stdout = io::stdout();

    writeln!(&mut stdout, "Hello {}!", "world").unwrap();
}

print!

fn main() {
    print!("Hello {}!", "world");
}

println!

fn main() {
    println!("Hello {}!", "world");
}

eprint!

fn main() {
    eprint!("Hello {}!", "world");
}

eprintln!

fn main() {
    eprintln!("Hello {}!", "world");
}

其它会格式化文字的宏

标准函数库中有些不在 std::fmt 模块内的宏也会去格式化文字,例如在前面的章节使用过的 panic!、assert!、assert_eq!、assert_ne!。

举例来说:

fn main() {
    assert_eq!(0, 0, "Hello {}!", "world");

    panic!("Ahh, {}!", "panic");
}

结论

Rust 编程语言的标准函数库提供的宏时常会用到格式化文字的功能,也因此清楚了解格式化文字的方式将有助于我们使用这些宏,甚至是撰写出我们自己的宏。

在下一章节,我们就是要来学习如何创建出自己的宏。

下一章:宏。