src/libcore/ops/index.rs

   1 /// Used for indexing operations (`container[index]`) in immutable contexts.
   2 ///
   3 /// `container[index]` is actually syntactic sugar for `*container.index(index)`,
   4 /// but only when used as an immutable value. If a mutable value is requested,
   5 /// [`IndexMut`] is used instead. This allows nice things such as
   6 /// `let value = v[index]` if the type of `value` implements [`Copy`].
   7 ///
   8 /// [`IndexMut`]: ../../std/ops/trait.IndexMut.html
   9 /// [`Copy`]: ../../std/marker/trait.Copy.html
  10 ///
  11 /// # Examples
  12 ///
  13 /// The following example implements `Index` on a read-only `NucleotideCount`
  14 /// container, enabling individual counts to be retrieved with index syntax.
  15 ///
  16 /// ```
  17 /// use std::ops::Index;
  18 ///
  19 /// enum Nucleotide {
  20 ///     A,
  21 ///     C,
  22 ///     G,
  23 ///     T,
  24 /// }
  25 ///
  26 /// struct NucleotideCount {
  27 ///     a: usize,
  28 ///     c: usize,
  29 ///     g: usize,
  30 ///     t: usize,
  31 /// }
  32 ///
  33 /// impl Index<Nucleotide> for NucleotideCount {
  34 ///     type Output = usize;
  35 ///
  36 ///     fn index(&self, nucleotide: Nucleotide) -> &Self::Output {
  37 ///         match nucleotide {
  38 ///             Nucleotide::A => &self.a,
  39 ///             Nucleotide::C => &self.c,
  40 ///             Nucleotide::G => &self.g,
  41 ///             Nucleotide::T => &self.t,
  42 ///         }
  43 ///     }
  44 /// }
  45 ///
  46 /// let nucleotide_count = NucleotideCount {a: 14, c: 9, g: 10, t: 12};
  47 /// assert_eq!(nucleotide_count[Nucleotide::A], 14);
  48 /// assert_eq!(nucleotide_count[Nucleotide::C], 9);
  49 /// assert_eq!(nucleotide_count[Nucleotide::G], 10);
  50 /// assert_eq!(nucleotide_count[Nucleotide::T], 12);
  51 /// ```
  52 #[lang = "index"]
  53 #[rustc_on_unimplemented(
  54     message = "the type `{Self}` cannot be indexed by `{Idx}`",
  55     label = "`{Self}` cannot be indexed by `{Idx}`"
  56 )]
  57 #[stable(feature = "rust1", since = "1.0.0")]
  58 #[doc(alias = "]")]
  59 #[doc(alias = "[")]
  60 #[doc(alias = "[]")]
  61 pub trait Index<Idx: ?Sized> {
  62     /// The returned type after indexing.
  63     #[stable(feature = "rust1", since = "1.0.0")]
  64     type Output: ?Sized;
  65
  66     /// Performs the indexing (`container[index]`) operation.
  67     #[stable(feature = "rust1", since = "1.0.0")]
  68     fn index(&self, index: Idx) -> &Self::Output;
  69 }
  70
  71 /// Used for indexing operations (`container[index]`) in mutable contexts.
  72 ///
  73 /// `container[index]` is actually syntactic sugar for
  74 /// `*container.index_mut(index)`, but only when used as a mutable value. If
  75 /// an immutable value is requested, the [`Index`] trait is used instead. This
  76 /// allows nice things such as `v[index] = value`.
  77 ///
  78 /// [`Index`]: ../../std/ops/trait.Index.html
  79 ///
  80 /// # Examples
  81 ///
  82 /// A very simple implementation of a `Balance` struct that has two sides, where
  83 /// each can be indexed mutably and immutably.
  84 ///
  85 /// ```
  86 /// use std::ops::{Index,IndexMut};
  87 ///
  88 /// #[derive(Debug)]
  89 /// enum Side {
  90 ///     Left,
  91 ///     Right,
  92 /// }
  93 ///
  94 /// #[derive(Debug, PartialEq)]
  95 /// enum Weight {
  96 ///     Kilogram(f32),
  97 ///     Pound(f32),
  98 /// }
  99 ///
 100 /// struct Balance {
 101 ///     pub left: Weight,
 102 ///     pub right: Weight,
 103 /// }
 104 ///
 105 /// impl Index<Side> for Balance {
 106 ///     type Output = Weight;
 107 ///
 108 ///     fn index(&self, index: Side) -> &Self::Output {
 109 ///         println!("Accessing {:?}-side of balance immutably", index);
 110 ///         match index {
 111 ///             Side::Left => &self.left,
 112 ///             Side::Right => &self.right,
 113 ///         }
 114 ///     }
 115 /// }
 116 ///
 117 /// impl IndexMut<Side> for Balance {
 118 ///     fn index_mut(&mut self, index: Side) -> &mut Self::Output {
 119 ///         println!("Accessing {:?}-side of balance mutably", index);
 120 ///         match index {
 121 ///             Side::Left => &mut self.left,
 122 ///             Side::Right => &mut self.right,
 123 ///         }
 124 ///     }
 125 /// }
 126 ///
 127 /// let mut balance = Balance {
 128 ///     right: Weight::Kilogram(2.5),
 129 ///     left: Weight::Pound(1.5),
 130 /// };
 131 ///
 132 /// // In this case, `balance[Side::Right]` is sugar for
 133 /// // `*balance.index(Side::Right)`, since we are only *reading*
 134 /// // `balance[Side::Right]`, not writing it.
 135 /// assert_eq!(balance[Side::Right], Weight::Kilogram(2.5));
 136 ///
 137 /// // However, in this case `balance[Side::Left]` is sugar for
 138 /// // `*balance.index_mut(Side::Left)`, since we are writing
 139 /// // `balance[Side::Left]`.
 140 /// balance[Side::Left] = Weight::Kilogram(3.0);
 141 /// ```
 142 #[lang = "index_mut"]
 143 #[rustc_on_unimplemented(
 144     on(
 145         _Self = "&str",
 146         note = "you can use `.chars().nth()` or `.bytes().nth()`
 147 see chapter in The Book <https://doc.rust-lang.org/book/ch08-02-strings.html#indexing-into-strings>"
 148     ),
 149     on(
 150         _Self = "str",
 151         note = "you can use `.chars().nth()` or `.bytes().nth()`
 152 see chapter in The Book <https://doc.rust-lang.org/book/ch08-02-strings.html#indexing-into-strings>"
 153     ),
 154     on(
 155         _Self = "std::string::String",
 156         note = "you can use `.chars().nth()` or `.bytes().nth()`
 157 see chapter in The Book <https://doc.rust-lang.org/book/ch08-02-strings.html#indexing-into-strings>"
 158     ),
 159     message = "the type `{Self}` cannot be mutably indexed by `{Idx}`",
 160     label = "`{Self}` cannot be mutably indexed by `{Idx}`"
 161 )]
 162 #[stable(feature = "rust1", since = "1.0.0")]
 163 #[doc(alias = "[")]
 164 #[doc(alias = "]")]
 165 #[doc(alias = "[]")]
 166 pub trait IndexMut<Idx: ?Sized>: Index<Idx> {
 167     /// Performs the mutable indexing (`container[index]`) operation.
 168     #[stable(feature = "rust1", since = "1.0.0")]
 169     fn index_mut(&mut self, index: Idx) -> &mut Self::Output;
 170 }