@@ -1645,7 +1645,7 @@ rem_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
16451645#[ lang = "bitand_assign" ]
16461646#[ stable( feature = "op_assign_traits" , since = "1.8.0" ) ]
16471647pub trait BitAndAssign < Rhs =Self > {
1648- /// The method for the `&` operator
1648+ /// The method for the `&= ` operator
16491649 #[ stable( feature = "op_assign_traits" , since = "1.8.0" ) ]
16501650 fn bitand_assign ( & mut self , Rhs ) ;
16511651}
@@ -1879,10 +1879,18 @@ shr_assign_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
18791879/// The `Index` trait is used to specify the functionality of indexing operations
18801880/// like `container[index]` when used in an immutable context.
18811881///
1882+ /// `container[index]` is actually syntactic sugar for `*container.index(index)`,
1883+ /// but only when used as an immutable value. If a mutable value is requested,
1884+ /// [`IndexMut`] is used instead. This allows nice things such as
1885+ /// `let value = v[index]` if `value` implements [`Copy`].
1886+ ///
1887+ /// [`IndexMut`]: ../../std/ops/trait.IndexMut.html
1888+ /// [`Copy`]: ../../std/marker/trait.Copy.html
1889+ ///
18821890/// # Examples
18831891///
1884- /// This example implements `Index` on a read-only `NucleotideCount` container,
1885- /// enabling individual counts to be retrieved with index syntax.
1892+ /// The following example implements `Index` on a read-only `NucleotideCount`
1893+ /// container, enabling individual counts to be retrieved with index syntax.
18861894///
18871895/// ```
18881896/// use std::ops::Index;
@@ -1934,37 +1942,78 @@ pub trait Index<Idx: ?Sized> {
19341942}
19351943
19361944/// The `IndexMut` trait is used to specify the functionality of indexing
1937- /// operations like `container[index]`, when used in a mutable context.
1945+ /// operations like `container[index]` when used in a mutable context.
1946+ ///
1947+ /// `container[index]` is actually syntactic sugar for
1948+ /// `*container.index_mut(index)`, but only when used as a mutable value. If
1949+ /// an immutable value is requested, the [`Index`] trait is used instead. This
1950+ /// allows nice things such as `v[index] = value` if `value` implements [`Copy`].
1951+ ///
1952+ /// [`Index`]: ../../std/ops/trait.Index.html
1953+ /// [`Copy`]: ../../std/marker/trait.Copy.html
19381954///
19391955/// # Examples
19401956///
1941- /// A trivial implementation of `IndexMut` for a type `Foo`. When `&mut Foo[2]`
1942- /// happens, it ends up calling `index_mut`, and therefore, `main` prints
1943- /// `Mutable indexing with 2!`.
1957+ /// A very simple implementation of a `Balance` struct that has two sides, where
1958+ /// each can be indexed mutably and immutably.
19441959///
19451960/// ```
1946- /// use std::ops::{Index, IndexMut};
1961+ /// use std::ops::{Index,IndexMut};
19471962///
1948- /// #[derive(Copy, Clone)]
1949- /// struct Foo;
1963+ /// #[derive(Debug)]
1964+ /// enum Side {
1965+ /// Left,
1966+ /// Right,
1967+ /// }
19501968///
1951- /// impl Index<usize> for Foo {
1952- /// type Output = Foo;
1969+ /// #[derive(Debug, PartialEq)]
1970+ /// enum Weight {
1971+ /// Kilogram(f32),
1972+ /// Pound(f32),
1973+ /// }
1974+ ///
1975+ /// struct Balance {
1976+ /// pub left: Weight,
1977+ /// pub right:Weight,
1978+ /// }
19531979///
1954- /// fn index(&self, _index: usize) -> &Foo {
1955- /// self
1980+ /// impl Index<Side> for Balance {
1981+ /// type Output = Weight;
1982+ ///
1983+ /// fn index<'a>(&'a self, index: Side) -> &'a Weight {
1984+ /// println!("Accessing {:?}-side of balance immutably", index);
1985+ /// match index {
1986+ /// Side::Left => &self.left,
1987+ /// Side::Right => &self.right,
1988+ /// }
19561989/// }
19571990/// }
19581991///
1959- /// impl IndexMut<usize> for Foo {
1960- /// fn index_mut(&mut self, index: usize) -> &mut Foo {
1961- /// println!("Mutable indexing with {}!", index);
1962- /// self
1992+ /// impl IndexMut<Side> for Balance {
1993+ /// fn index_mut<'a>(&'a mut self, index: Side) -> &'a mut Weight {
1994+ /// println!("Accessing {:?}-side of balance mutably", index);
1995+ /// match index {
1996+ /// Side::Left => &mut self.left,
1997+ /// Side::Right => &mut self.right,
1998+ /// }
19631999/// }
19642000/// }
19652001///
19662002/// fn main() {
1967- /// &mut Foo[2];
2003+ /// let mut balance = Balance {
2004+ /// right: Weight::Kilogram(2.5),
2005+ /// left: Weight::Pound(1.5),
2006+ /// };
2007+ ///
2008+ /// // In this case balance[Side::Right] is sugar for
2009+ /// // *balance.index(Side::Right), since we are only reading
2010+ /// // balance[Side::Right], not writing it.
2011+ /// assert_eq!(balance[Side::Right],Weight::Kilogram(2.5));
2012+ ///
2013+ /// // However in this case balance[Side::Left] is sugar for
2014+ /// // *balance.index_mut(Side::Left), since we are writing
2015+ /// // balance[Side::Left].
2016+ /// balance[Side::Left] = Weight::Kilogram(3.0);
19682017/// }
19692018/// ```
19702019#[ lang = "index_mut" ]
0 commit comments