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

时间:2017-02-02 00:17:41

标签: rust naming-conventions

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

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

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

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

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

  • foo_ref() | foo_mut()

    用于Any.downcast_refAny.downcast_mut

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

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

1 个答案:

答案 0 :(得分:7)

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

  

规则

     

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

     

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

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

但是,对于迭代器,移动变体也可以理解为into转换,into_iterfor 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上命名方法会导致另一方影响。所以整个画面是: