Module alloc::fmt1.0.0[−][src]

Expand description

用于格式化和打印 Strings 的实用工具。

该模块包含对 format! 语法扩展的运行时支持。该宏在编译器中实现，以发出对该模块的调用，以便在运行时将参数格式化为字符串。

Usage

format! 宏旨在使那些使用 C 的 printf/fprintf 函数或 Python 的 str.format 函数的用户熟悉。

format! 扩展的一些示例是：

format!("Hello");                 // => "Hello"
format!("Hello, {}!", "world");   // => "Hello, world!"
format!("The number is {}", 1);   // => "The number is 1"
format!("{:?}", (3, 4));          // => "(3, 4)"
format!("{value}", value=4);      // => "4"
let people = "Rustaceans";
format!("Hello {people}!");       // => "Hello Rustaceans!"
format!("{} {}", 1, 2);           // => "1 2"
format!("{:04}", 42);             // => 带前导零的 "0042"
format!("{:#?}", (100, 200));     // => "(
                                  // 100,
                                  //       200, )"
                                  //

Run

从这些中，您可以看到第一个参数是格式字符串。编译器要求它是字符串字面量；它不能是传入的变量 (以执行有效性检查)。然后，编译器将解析格式字符串，并确定所提供的参数列表是否适合传递给该格式字符串。

要将单个值转换为字符串，请使用 to_string 方法。这将使用 Display 格式 trait。

位置参数

每个格式化参数都可以指定它引用的值参数，如果省略，则假定它是 “下一个参数”。例如，格式字符串 {} {} {} 将带有三个参数，并且将按照给定的顺序对其进行格式化。但是，格式字符串 {2} {1} {0} 将以相反的顺序格式化参数。

一旦开始将两种类型的位置说明符混合在一起，事情就会变得有些棘手。可以将 “下一个参数” 说明符可以看作是参数的迭代器。每次看到 “下一个参数” 说明符时，迭代器都会前进。这会导致这样的行为：

format!("{1} {} {0} {}", 1, 2); // => "2 1 1 2"

Run

看到第一个 {} 时，尚未对参数进行内部迭代，因此它将打印第一个参数。然后，在到达第二个 {} 时，迭代器已前进到第二个参数。本质上，在位置说明符方面，明确命名其参数的参数不会影响未命名参数的参数。

必须使用格式字符串才能使用其所有参数，否则将导致编译时错误。您可能在格式字符串中多次引用同一参数。

命名参数

Rust 本身不具有类似于 Python 的等效于函数的命名参数，但是 format! 宏是一种语法扩展，允许它利用命名参数。命名参数列在参数列表的末尾，并具有以下语法：

identifier '=' expression

例如，以下 format! 表达式都使用命名参数：

format!("{argument}", argument = "test");   // => "test"
format!("{name} {}", 1, name = 2);          // => "2 1"
format!("{a} {c} {b}", a="a", b='b', c=3);  // => "a 3 b"

Run

如果命名参数没有出现在参数列表中，format! 将引用当前作用域中的同名变量。

let argument = 2 + 2;
format!("{argument}");   // => "4"

fn make_string(a: u32, b: &str) -> String {
    format!("{b} {a}")
}
make_string(927, "label"); // => "label 927"

Run

在具有名称的参数之后放置位置参数 (那些没有名称的参数) 是无效的。与位置参数一样，提供格式字符串未使用的命名参数也是无效的。

格式化 traits

当请求使用特定类型的参数格式化时，实际上是在请求将参数归因于特定的 trait。这允许通过 {:x} 格式化多种实际类型 (例如 i8 和 isize)。类型到 traits 的当前映射是：

nothing ⇒ Display
? ⇒ Debug
x? ⇒ Debug 带有小写十六进制整数
X? ⇒ Debug 带有大写十六进制整数
o ⇒ Octal
x ⇒ LowerHex
X ⇒ UpperHex
p ⇒ Pointer
b ⇒ Binary
e ⇒ LowerExp
E ⇒ UpperExp

这意味着可以使用 {:b} 格式化实现 fmt::Binary trait 的任何类型的参数。标准库还为许多原始类型提供了针对这些 traits 的实现。

如果未指定格式 (如 {} 或 {:6})，则使用的格式 trait 为 Display trait。

当为您自己的类型实现格式 trait 时，您将必须实现签名的方法：

fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {

Run

您的类型将作为 self by - 引用传递，然后函数应将输出发出到 f.buf 流中。正确遵守所请求的格式设置参数，取决于每种格式 trait 的实现。这些参数的值将在 Formatter 结构体的字段中列出。为了解决这个问题，Formatter 结构体还提供了一些辅助方法。

此外，该函数的返回值是 fmt::Result，它是 Result<(), std::fmt::Error> 的类型别名。格式化实现应确保它们传播来自 Formatter 的错误 (例如，调用 write! 时)。但是，它们绝不能虚假地返回错误。即，格式化实现必须并且仅在传入的 Formatter 返回错误的情况下才返回错误。这是因为，与函数签名可能暗示的相反，字符串格式是一项可靠的操作。该函数仅返回结果，因为写入底层流可能会失败，并且它必须提供一种方法来将已发生错误的事实传播回栈。

实现格式 traits 的示例如下所示：

use std::fmt;

#[derive(Debug)]
struct Vector2D {
    x: isize,
    y: isize,
}

impl fmt::Display for Vector2D {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        // `f` 值实现 `Write` trait，这就是 `write`！ 宏正在等待。
        // 请注意，这种格式化将忽略为格式化字符串而提供的各种标志。
        //
        write!(f, "({}, {})", self.x, self.y)
    }
}

// 不同的 traits 允许类型的不同形式的输出。
// 此格式的含义是打印 vector 的大小。
impl fmt::Binary for Vector2D {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        let magnitude = (self.x * self.x + self.y * self.y) as f64;
        let magnitude = magnitude.sqrt();

        // 通过使用 Formatter 对象上的帮助器方法 `pad_integral`，尊重格式设置标志。
        // 有关详细信息，请参见方法文档，并且函数 `pad` 可用于填充字符串。
        //
        //
        let decimals = f.precision().unwrap_or(3);
        let string = format!("{:.*}", decimals, magnitude);
        f.pad_integral(true, "", &string)
    }
}

fn main() {
    let myvector = Vector2D { x: 3, y: 4 };

    println!("{}", myvector);       // => "(3, 4)"
    println!("{:?}", myvector);     // => "Vector2D {x: 3, y:4}"
    println!("{:10.3b}", myvector); // => "     5.000"
}

Run

`fmt::Display` 与 `fmt::Debug`

这两种格式 traits 具有不同的用途：

fmt::Display 实现断言该类型可以始终忠实地表示为 UTF-8 字符串。并非所有类型都实现 Display trait。
fmt::Debug 实现应该为所有公共类型实现。输出通常会尽可能忠实地代表内部状态。 Debug trait 的目的是方便调试 Rust 代码。在大多数情况下，建议使用 #[derive(Debug)] 就足够了。

这两个 traits 的输出的一些例子：

assert_eq!(format!("{} {:?}", 3, 4), "3 4");
assert_eq!(format!("{} {:?}", 'a', 'b'), "a 'b'");
assert_eq!(format!("{} {:?}", "foo\n", "bar\n"), "foo\n \"bar\\n\"");