src/docs/trivially_copy_pass_by_ref.txt

   1 ### What it does
   2 Checks for functions taking arguments by reference, where
   3 the argument type is `Copy` and small enough to be more efficient to always
   4 pass by value.
   5
   6 ### Why is this bad?
   7 In many calling conventions instances of structs will
   8 be passed through registers if they fit into two or less general purpose
   9 registers.
  10
  11 ### Known problems
  12 This lint is target register size dependent, it is
  13 limited to 32-bit to try and reduce portability problems between 32 and
  14 64-bit, but if you are compiling for 8 or 16-bit targets then the limit
  15 will be different.
  16
  17 The configuration option `trivial_copy_size_limit` can be set to override
  18 this limit for a project.
  19
  20 This lint attempts to allow passing arguments by reference if a reference
  21 to that argument is returned. This is implemented by comparing the lifetime
  22 of the argument and return value for equality. However, this can cause
  23 false positives in cases involving multiple lifetimes that are bounded by
  24 each other.
  25
  26 Also, it does not take account of other similar cases where getting memory addresses
  27 matters; namely, returning the pointer to the argument in question,
  28 and passing the argument, as both references and pointers,
  29 to a function that needs the memory address. For further details, refer to
  30 [this issue](https://github.com/rust-lang/rust-clippy/issues/5953)
  31 that explains a real case in which this false positive
  32 led to an **undefined behavior** introduced with unsafe code.
  33
  34 ### Example
  35
  36 ```
  37 fn foo(v: &u32) {}
  38 ```
  39
  40 Use instead:
  41 ```
  42 fn foo(v: u32) {}
  43 ```