编写API时,通常会有一个方法的可变版本和不可变版本。
我希望标准库有关于如何命名这些的明确约定,但它并不完全一致 1 :
以下方法有哪些好的命名约定?
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 :这可能是一致的,我只是没有注意到这个推理。
答案 0 :(得分:7)
是的,此约定在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