src/doc/style/style/naming/ownership.md

   1 % Ownership variants [RFC #199]
   2
   3 > The guidelines below were approved by [RFC #199](https://github.com/rust-lang/rfcs/pull/199).
   4
   5 Functions often come in multiple variants: immutably borrowed, mutably
   6 borrowed, and owned.
   7
   8 The right default depends on the function in question. Variants should
   9 be marked through suffixes.
  10
  11 #### Immutably borrowed by default
  12
  13 If `foo` uses/produces an immutable borrow by default, use:
  14
  15 * The `_mut` suffix (e.g. `foo_mut`) for the mutably borrowed variant.
  16 * The `_move` suffix (e.g. `foo_move`) for the owned variant.
  17
  18 #### Owned by default
  19
  20 If `foo` uses/produces owned data by default, use:
  21
  22 * The `_ref` suffix (e.g. `foo_ref`) for the immutably borrowed variant.
  23 * The `_mut` suffix (e.g. `foo_mut`) for the mutably borrowed variant.
  24
  25 #### Exceptions
  26
  27 In the case of iterators, the moving variant can also be understood as
  28 an `into` conversion, `into_iter`, and `for x in v.into_iter()` reads
  29 arguably better than `for x in v.iter_move()`, so the convention is
  30 `into_iter`.
  31
  32 For mutably borrowed variants, if the `mut` qualifier is part of a
  33 type name (e.g. `as_mut_slice`), it should appear as it would appear
  34 in the type.