src/doc/style/features/traits/generics.md

   1 % Using traits for bounds on generics
   2
   3 The most widespread use of traits is for writing generic functions or types. For
   4 example, the following signature describes a function for consuming any iterator
   5 yielding items of type `A` to produce a collection of `A`:
   6
   7 ```rust
   8 fn from_iter<T: Iterator<A>>(iterator: T) -> SomeCollection<A>
   9 ```
  10
  11 Here, the `Iterator` trait specifies an interface that a type `T` must
  12 explicitly implement to be used by this generic function.
  13
  14 **Pros**:
  15
  16 * _Reusability_. Generic functions can be applied to an open-ended collection of
  17   types, while giving a clear contract for the functionality those types must
  18   provide.
  19 * _Static dispatch and optimization_. Each use of a generic function is
  20   specialized ("monomorphized") to the particular types implementing the trait
  21   bounds, which means that (1) invocations of trait methods are static, direct
  22   calls to the implementation and (2) the compiler can inline and otherwise
  23   optimize these calls.
  24 * _Inline layout_. If a `struct` and `enum` type is generic over some type
  25   parameter `T`, values of type `T` will be laid out _inline_ in the
  26   `struct`/`enum`, without any indirection.
  27 * _Inference_. Since the type parameters to generic functions can usually be
  28   inferred, generic functions can help cut down on verbosity in code where
  29   explicit conversions or other method calls would usually be necessary. See the
  30   [overloading/implicits use case](#use-case:-limited-overloading-and/or-implicit-conversions)
  31   below.
  32 * _Precise types_. Because generic give a _name_ to the specific type
  33   implementing a trait, it is possible to be precise about places where that
  34   exact type is required or produced. For example, a function
  35
  36   ```rust
  37   fn binary<T: Trait>(x: T, y: T) -> T
  38   ```
  39
  40   is guaranteed to consume and produce elements of exactly the same type `T`; it
  41   cannot be invoked with parameters of different types that both implement
  42   `Trait`.
  43
  44 **Cons**:
  45
  46 * _Code size_. Specializing generic functions means that the function body is
  47   duplicated. The increase in code size must be weighed against the performance
  48   benefits of static dispatch.
  49 * _Homogeneous types_. This is the other side of the "precise types" coin: if
  50   `T` is a type parameter, it stands for a _single_ actual type. So for example
  51   a `Vec<T>` contains elements of a single concrete type (and, indeed, the
  52   vector representation is specialized to lay these out in line). Sometimes
  53   heterogeneous collections are useful; see
  54   [trait objects](#use-case:-trait-objects) below.
  55 * _Signature verbosity_. Heavy use of generics can bloat function signatures.
  56   **[Ed. note]** This problem may be mitigated by some language improvements; stay tuned.
  57
  58 ### Favor widespread traits. **[FIXME: needs RFC]**
  59
  60 Generic types are a form of abstraction, which entails a mental indirection: if
  61 a function takes an argument of type `T` bounded by `Trait`, clients must first
  62 think about the concrete types that implement `Trait` to understand how and when
  63 the function is callable.
  64
  65 To keep the cost of abstraction low, favor widely-known traits. Whenever
  66 possible, implement and use traits provided as part of the standard library.  Do
  67 not introduce new traits for generics lightly; wait until there are a wide range
  68 of types that can implement the type.