2.2.1.10 To

译文 · 基于 Comprehensive Rust

原文链接: https://google.github.io/comprehensive-rust/idiomatic/foundations-api-design/predictable-api/naming-conventions/to.html

2.2.1.10 To

接受借用值并创建拥有所有权值的函数前缀。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// Copyright 2025 Google LLC
// SPDX-License-Identifier: Apache-2.0
impl str {
    fn to_owned(&self) -> String;

    fn to_uppercase(&self) -> String;
}

impl u32 {
    // 接受拥有所有权的 self，因为 `u32` 实现了 `Copy`
    fn to_be(self) -> u32;
}

• 在不消费 self 的情况下创建新的拥有所有权值、并暗示类型转换的方法，以 to 开头命名。

• 以 “to” 开头的方法返回不同类型，并强烈暗示非平凡的类型转换，甚至是数据变换。例如 str::to_uppercase。

• “to” 方法最常接受 &self。但若类型实现了 Copy，也可按值接受 self：这也确保转换方法调用不会消费 self。

• 若只想定义接受 &self 并返回同类型拥有所有权值的方法，实现 Clone 或 ToOwned。

• 若想定义消费源值的方法，使用 “into” 命名模式。

• 也见于转换原始类型字节序，或复制并暴露 newtype 值的函数。

延伸阅读

• 问问学员：to_owned 与 into_owned 有何区别？

  答案：to_owned 出现在 &str 这类引用值上，而 into_owned 出现在持有引用类型的拥有所有权值上，如 Cow（copy-on-write）。

  像 Cow 这样的类型可以在拥有所有权的同时包含借用的引用，因此消费 Cow 的拥有所有权值，以创建其所持引用类型的拥有所有权值。