命名可变/不可变API函数的约定？

Question

编写API时,通常会有一个方法的可变和不可变版本.

我希望标准库有关于如何命名这些的明确约定,但它并不完全一致¹:

以下方法的命名约定有哪些？

pub fn foo****(&self) -> &Bar { ... }
pub fn foo****(&mut self) -> &mut Bar { ... }

• foo() | foo_mut()

  这似乎是最常见的,可以在Vec.iter和中看到Vec.iter_mut.

• foo_ref() | foo_mut()

  用于Any.downcast_ref和Any.downcast_mut.

似乎第一种情况更常见,那么_ref在命名API函数时使用后缀的原因是什么？

---

1:这可能是一致的,我只是没有注意到推理.

Answer 1

是的,对此的约定在RFC 199中定义.重要的是:

规则

默认情况下不可避免地借用

如果foo默认情况下使用/生成不可变借用,请使用:

• 可变借用变体的_mut后缀(例如foo_mut).
• 拥有变体的_move后缀(例如foo_move).

但是,在迭代器的情况下,移动变体也可以被理解为into转换into_iter,并且可以理解for x in v.into_iter()地比读取更好for x in v.iter_move(),因此约定是into_iter.

注意:此约定仅涵盖迭代器的方法名称,而不包括迭代器类型的名称.这将是后续RFC的主题.

默认拥有

如果foo默认使用/生成拥有的数据,请使用:

• 不可变借入的变体的_ref后缀(例如foo_ref).
• 可变借用变体的_mut后缀(例如foo_mut).

Any::downcast_ref不叫downcast,因为有一个名为方法downcast上Box<Any + 'static>和Box<Any + 'static + Send>这需要self通过值.命名方法Any downcast会导致一个人影响另一个.所以整个画面是:

• downcast,采取self,定义Box<Any + 'static>和Box<Any + 'static + Send>
• downcast_ref,采取&self,定义Any + 'static和Any + 'static + Send
• downcast_mut,采取&mut self,定义Any + 'static和Any + 'static + Send