@@ -1645,7 +1645,7 @@ rem_assign_impl! { usize u8 u16 u32 u64 isize i8 i16 i32 i64 f32 f64 }
1645
1645
#[ lang = "bitand_assign" ]
1646
1646
#[ stable( feature = "op_assign_traits" , since = "1.8.0" ) ]
1647
1647
pub trait BitAndAssign < Rhs =Self > {
1648
- /// The method for the `&` operator
1648
+ /// The method for the `&= ` operator
1649
1649
#[ stable( feature = "op_assign_traits" , since = "1.8.0" ) ]
1650
1650
fn bitand_assign ( & mut self , Rhs ) ;
1651
1651
}
@@ -1879,10 +1879,18 @@ shr_assign_impl_all! { u8 u16 u32 u64 usize i8 i16 i32 i64 isize }
1879
1879
/// The `Index` trait is used to specify the functionality of indexing operations
1880
1880
/// like `container[index]` when used in an immutable context.
1881
1881
///
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
+ ///
1882
1890
/// # Examples
1883
1891
///
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.
1886
1894
///
1887
1895
/// ```
1888
1896
/// use std::ops::Index;
@@ -1934,37 +1942,78 @@ pub trait Index<Idx: ?Sized> {
1934
1942
}
1935
1943
1936
1944
/// 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
1938
1954
///
1939
1955
/// # Examples
1940
1956
///
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.
1944
1959
///
1945
1960
/// ```
1946
- /// use std::ops::{Index, IndexMut};
1961
+ /// use std::ops::{Index,IndexMut};
1947
1962
///
1948
- /// #[derive(Copy, Clone)]
1949
- /// struct Foo;
1963
+ /// #[derive(Debug)]
1964
+ /// enum Side {
1965
+ /// Left,
1966
+ /// Right,
1967
+ /// }
1950
1968
///
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
+ /// }
1953
1979
///
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
+ /// }
1956
1989
/// }
1957
1990
/// }
1958
1991
///
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
+ /// }
1963
1999
/// }
1964
2000
/// }
1965
2001
///
1966
2002
/// 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);
1968
2017
/// }
1969
2018
/// ```
1970
2019
#[ lang = "index_mut" ]
0 commit comments