命名可变/不可变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。

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

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，因为在Box<Any + 'static>和Box<Any + 'static + Send>上有一个名为downcast的方法，其值为self 。在Any downcast上命名方法会导致另一方影响。所以整个画面是：

• downcast，在Box<Any + 'static>和Box<Any + 'static + Send>上定义self
• downcast_ref，在Any + 'static和Any + 'static + Send上定义&self
• downcast_mut，在Any + 'static和Any + 'static + Send上定义&mut self