std::ops docs: incorporated changes suggested in review
* fixed link typos and copy-paster errors * rewrote Fn* explanations * `RHS = Self` -> `RHS` is `Self` (added that to all applicable places as well) * fixed up some links * s/MutDeref/DerefMut * removed remaining superfluous `fn main()`s * fixed some minor phrasings and factual errors and inaccuracies std::ops docs: Fix phrasing and factual errors/inaccuracies
This commit is contained in:
lukaramu
parent
99e44d8680
commit
6bdba82ba1
6 changed files with 82 additions and 58 deletions
|
|
@ -10,8 +10,8 @@
|
|||
|
||||
/// The addition operator `+`.
|
||||
///
|
||||
/// Note that `RHS = Self` by default, but this is not mandatory. For example,
|
||||
/// [`std::time::SystemTime`] implements `Add<Duration>`, which permits
|
||||
/// Note that `RHS` is `Self` by default, but this is not mandatory. For
|
||||
/// example, [`std::time::SystemTime`] implements `Add<Duration>`, which permits
|
||||
/// operations of the form `SystemTime = SystemTime + Duration`.
|
||||
///
|
||||
/// [`std::time::SystemTime`]: ../../std/time/struct.SystemTime.html
|
||||
|
|
@ -105,8 +105,8 @@ add_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f32 f64 }
|
|||
|
||||
/// The subtraction operator `-`.
|
||||
///
|
||||
/// Note that `RHS = Self` by default, but this is not mandatory. For example,
|
||||
/// [std::time::SystemTime] implements `Sub<Duration>`, which permits
|
||||
/// Note that `RHS` is `Self` by default, but this is not mandatory. For
|
||||
/// example, [`std::time::SystemTime`] implements `Sub<Duration>`, which permits
|
||||
/// operations of the form `SystemTime = SystemTime - Duration`.
|
||||
///
|
||||
/// [`std::time::SystemTime`]: ../../std/time/struct.SystemTime.html
|
||||
|
|
@ -200,7 +200,7 @@ sub_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f32 f64 }
|
|||
|
||||
/// The multiplication operator `*`.
|
||||
///
|
||||
/// Note that `RHS = Self` by default, but this is not mandatory.
|
||||
/// Note that `RHS` is `Self` by default, but this is not mandatory.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
@ -317,7 +317,7 @@ mul_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f32 f64 }
|
|||
|
||||
/// The division operator `/`.
|
||||
///
|
||||
/// Note that `RHS = Self` by default, but this is not mandatory.
|
||||
/// Note that `RHS` is `Self` by default, but this is not mandatory.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
@ -455,6 +455,8 @@ div_impl_float! { f32 f64 }
|
|||
|
||||
/// The remainder operator `%`.
|
||||
///
|
||||
/// Note that `RHS` is `Self` by default, but this is not mandatory.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// This example implements `Rem` on a `SplitSlice` object. After `Rem` is
|
||||
|
|
|
|||
|
|
@ -68,6 +68,8 @@ not_impl! { bool usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
|
|||
|
||||
/// The bitwise AND operator `&`.
|
||||
///
|
||||
/// Note that `RHS` is `Self` by default, but this is not mandatory.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// An implementation of `BitAnd` for a wrapper around `bool`.
|
||||
|
|
@ -147,6 +149,8 @@ bitand_impl! { bool usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
|
|||
|
||||
/// The bitwise OR operator `|`.
|
||||
///
|
||||
/// Note that `RHS` is `Self` by default, but this is not mandatory.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// An implementation of `BitOr` for a wrapper around `bool`.
|
||||
|
|
@ -226,6 +230,8 @@ bitor_impl! { bool usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 }
|
|||
|
||||
/// The bitwise XOR operator `^`.
|
||||
///
|
||||
/// Note that `RHS` is `Self` by default, but this is not mandatory.
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
/// An implementation of `BitXor` that lifts `^` to a wrapper around `bool`.
|
||||
|
|
|
|||
|
|
@ -111,7 +111,7 @@ impl<'a, T: ?Sized> Deref for &'a mut T {
|
|||
///
|
||||
/// # More on `Deref` coercion
|
||||
///
|
||||
/// If `T` implements `MutDeref<Target = U>`, and `x` is a value of type `T`,
|
||||
/// If `T` implements `DerefMut<Target = U>`, and `x` is a value of type `T`,
|
||||
/// then:
|
||||
/// * In mutable contexts, `*x` on non-pointer types is equivalent to
|
||||
/// `*Deref::deref(&x)`.
|
||||
|
|
|
|||
|
|
@ -8,27 +8,39 @@
|
|||
// option. This file may not be copied, modified, or distributed
|
||||
// except according to those terms.
|
||||
|
||||
/// A version of the call operator that takes an immutable receiver.
|
||||
/// The version of the call operator that takes an immutable receiver.
|
||||
///
|
||||
/// Closures only taking immutable references to captured variables
|
||||
/// automatically implement this trait, which allows them to be invoked.
|
||||
/// For mutably referenced captures, see [`FnMut`], and for consuming the
|
||||
/// capture, see [`FnOnce`].
|
||||
/// Instances of `Fn` can be called repeatedly without mutating state.
|
||||
///
|
||||
/// You can use the [`Fn`] traits when you want to accept a closure as a
|
||||
/// parameter. Since both [`FnMut`] and [`FnOnce`] are supertraits of `Fn`, any
|
||||
/// instance of `Fn` can be used where a [`FnMut`] or [`FnOnce`] is expected.
|
||||
/// *This trait (`Fn`) is not to be confused with [function pointers][]
|
||||
/// (`fn`).*
|
||||
///
|
||||
/// `Fn` is implemented automatically by closures which only take immutable
|
||||
/// references to captured variables or don't capture anything at all, as well
|
||||
/// as (safe) [function pointers][] (with some caveats, see their documentation
|
||||
/// for more details). Additionally, for any type `F` that implements `Fn`, `&F`
|
||||
/// implements `Fn`, too.
|
||||
///
|
||||
/// Since both [`FnMut`] and [`FnOnce`] are supertraits of `Fn`, any
|
||||
/// instance of `Fn` can be used as a parameter where a [`FnMut`] or [`FnOnce`]
|
||||
/// is expected.
|
||||
///
|
||||
/// Use `Fn` as a bound when you want to accept a parameter of function-like
|
||||
/// type and need to call it repeatedly and without mutating state (e.g. when
|
||||
/// calling it concurrently). If you do not need such strict requirements, use
|
||||
/// [`FnMut`] or [`FnOnce`] as bounds.
|
||||
///
|
||||
/// See the [chapter on closures in *The Rust Programming Language*][book] for
|
||||
/// more information about closures in general.
|
||||
/// some more information on this topic.
|
||||
///
|
||||
/// Also of note is the special syntax for `Fn` traits (e.g.
|
||||
/// `Fn(usize, bool) -> usize`). Those interested in the technical details of
|
||||
/// this can refer to [the relevant section in *The Rustonomicon*][nomicon].
|
||||
/// this can refer to [the relevant section in the *Rustonomicon*][nomicon].
|
||||
///
|
||||
/// [book]: ../../book/second-edition/ch13-01-closures.html
|
||||
/// [`FnMut`]: trait.FnMut.html
|
||||
/// [`FnOnce`]: trait.FnOnce.html
|
||||
/// [function pointers]: ../../std/primitive.fn.html
|
||||
/// [nomicon]: ../../nomicon/hrtb.html
|
||||
///
|
||||
/// # Examples
|
||||
|
|
@ -61,29 +73,36 @@ pub trait Fn<Args> : FnMut<Args> {
|
|||
extern "rust-call" fn call(&self, args: Args) -> Self::Output;
|
||||
}
|
||||
|
||||
/// A version of the call operator that takes a mutable receiver.
|
||||
/// The version of the call operator that takes a mutable receiver.
|
||||
///
|
||||
/// Closures that might mutably reference captured variables automatically
|
||||
/// implement this trait, which allows them to be invoked. For immutably
|
||||
/// referenced captures, see [`Fn`], and for consuming the captures, see
|
||||
/// [`FnOnce`].
|
||||
/// Instances of `FnMut` can be called repeatedly and may mutate state.
|
||||
///
|
||||
/// You can use the [`Fn`] traits when you want to accept a closure as a
|
||||
/// parameter. Since [`FnOnce`] is a supertrait of `FnMut`, any instance of
|
||||
/// `FnMut` can be used where a [`FnOnce`] is expected, and since [`Fn`] is a
|
||||
/// subtrait of `FnMut`, any instance of [`Fn`] can be used where [`FnMut`] is
|
||||
/// expected.
|
||||
/// `FnMut` is implemented automatically by closures which take mutable
|
||||
/// references to captured variables, as well as all types that implement
|
||||
/// [`Fn`], e.g. (safe) [function pointers][] (since `FnMut` is a supertrait of
|
||||
/// [`Fn`]). Additionally, for any type `F` that implements `FnMut`, `&mut F`
|
||||
/// implements `FnMut`, too.
|
||||
///
|
||||
/// Since [`FnOnce`] is a supertrait of `FnMut`, any instance of `FnMut` can be
|
||||
/// used where a [`FnOnce`] is expected, and since [`Fn`] is a subtrait of
|
||||
/// `FnMut`, any instance of [`Fn`] can be used where `FnMut` is expected.
|
||||
///
|
||||
/// Use `FnMut` as a bound when you want to accept a parameter of function-like
|
||||
/// type and need to call it repeatedly, while allowing it to mutate state.
|
||||
/// If you don't want the parameter to mutate state, use [`Fn`] as a
|
||||
/// bound; if you don't need to call it repeatedly, use [`FnOnce`].
|
||||
///
|
||||
/// See the [chapter on closures in *The Rust Programming Language*][book] for
|
||||
/// more information about closures in general.
|
||||
/// some more information on this topic.
|
||||
///
|
||||
/// Also of note is the special syntax for `Fn` traits (e.g.
|
||||
/// `Fn(usize, bool) -> usize`). Those interested in the technical details of
|
||||
/// this can refer to [the relevant section in *The Rustonomicon*][nomicon].
|
||||
/// this can refer to [the relevant section in the *Rustonomicon*][nomicon].
|
||||
///
|
||||
/// [book]: ../../book/second-edition/ch13-01-closures.html
|
||||
/// [`Fn`]: trait.Fnhtml
|
||||
/// [`Fn`]: trait.Fn.html
|
||||
/// [`FnOnce`]: trait.FnOnce.html
|
||||
/// [function pointers]: ../../std/primitive.fn.html
|
||||
/// [nomicon]: ../../nomicon/hrtb.html
|
||||
///
|
||||
/// # Examples
|
||||
|
|
@ -127,27 +146,35 @@ pub trait FnMut<Args> : FnOnce<Args> {
|
|||
extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output;
|
||||
}
|
||||
|
||||
/// A version of the call operator that takes a by-value receiver.
|
||||
/// The version of the call operator that takes a by-value receiver.
|
||||
///
|
||||
/// Closures that might take ownership of captured variables automatically
|
||||
/// implement this trait, which allows them to be invoked. For immutably
|
||||
/// referenced captures, see [`Fn`], and for mutably referenced captures,
|
||||
/// see [`FnMut`].
|
||||
/// Instances of `FnOnce` can be called, but might not be callable multiple
|
||||
/// times. Because of this, if the only thing known about a type is that it
|
||||
/// implements `FnOnce`, it can only be called once.
|
||||
///
|
||||
/// You can use the [`Fn`] traits when you want to accept a closure as a
|
||||
/// parameter. Since both [`Fn`] and [`FnMut`] are subtraits of `FnOnce`, any
|
||||
/// instance of [`Fn`] or [`FnMut`] can be used where a `FnOnce` is expected.
|
||||
/// `FnOnce` is implemented automatically by closure that might consume captured
|
||||
/// variables, as well as all types that implement [`FnMut`], e.g. (safe)
|
||||
/// [function pointers][] (since `FnOnce` is a supertrait of [`FnMut`]).
|
||||
///
|
||||
/// Since both [`Fn`] and [`FnMut`] are subtraits of `FnOnce`, any instance of
|
||||
/// [`Fn`] or [`FnMut`] can be used where a `FnOnce` is expected.
|
||||
///
|
||||
/// Use `FnOnce` as a bound when you want to accept a parameter of function-like
|
||||
/// type and only need to call it once. If you need to call the parameter
|
||||
/// repeatedly, use [`FnMut`] as a bound; if you also need it to not mutate
|
||||
/// state, use [`Fn`].
|
||||
///
|
||||
/// See the [chapter on closures in *The Rust Programming Language*][book] for
|
||||
/// more information about closures in general.
|
||||
/// some more information on this topic.
|
||||
///
|
||||
/// Also of note is the special syntax for `Fn` traits (e.g.
|
||||
/// `Fn(usize, bool) -> usize`). Those interested in the technical details of
|
||||
/// this can refer to [the relevant section in *The Rustonomicon*][nomicon].
|
||||
/// this can refer to [the relevant section in the *Rustonomicon*][nomicon].
|
||||
///
|
||||
/// [book]: ../../book/second-edition/ch13-01-closures.html
|
||||
/// [`Fn`]: trait.Fn.html
|
||||
/// [`FnMut`]: trait.FnMut.html
|
||||
/// [function pointers]: ../../std/primitive.fn.html
|
||||
/// [nomicon]: ../../nomicon/hrtb.html
|
||||
///
|
||||
/// # Examples
|
||||
|
|
|
|||
|
|
@ -77,11 +77,9 @@ pub trait Index<Idx: ?Sized> {
|
|||
/// `container[index]` is actually syntactic sugar for
|
||||
/// `*container.index_mut(index)`, but only when used as a mutable value. If
|
||||
/// an immutable value is requested, the [`Index`] trait is used instead. This
|
||||
/// allows nice things such as `v[index] = value` if the type of `value`
|
||||
/// implements [`Copy`].
|
||||
/// allows nice things such as `v[index] = value`.
|
||||
///
|
||||
/// [`Index`]: ../../std/ops/trait.Index.html
|
||||
/// [`Copy`]: ../../std/marker/trait.Copy.html
|
||||
///
|
||||
/// # Examples
|
||||
///
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ use fmt;
|
|||
|
||||
/// An unbounded range (`..`).
|
||||
///
|
||||
/// `RangeFull` is primarily used as a [slicing index], it's shorthand is `..`.
|
||||
/// `RangeFull` is primarily used as a [slicing index], its shorthand is `..`.
|
||||
/// It cannot serve as an [`Iterator`] because it doesn't have a starting point.
|
||||
///
|
||||
/// # Examples
|
||||
|
|
@ -101,7 +101,6 @@ impl<Idx: PartialOrd<Idx>> Range<Idx> {
|
|||
/// ```
|
||||
/// #![feature(range_contains)]
|
||||
///
|
||||
/// # fn main() {
|
||||
/// assert!(!(3..5).contains(2));
|
||||
/// assert!( (3..5).contains(3));
|
||||
/// assert!( (3..5).contains(4));
|
||||
|
|
@ -109,7 +108,6 @@ impl<Idx: PartialOrd<Idx>> Range<Idx> {
|
|||
///
|
||||
/// assert!(!(3..3).contains(3));
|
||||
/// assert!(!(3..2).contains(3));
|
||||
/// # }
|
||||
/// ```
|
||||
pub fn contains(&self, item: Idx) -> bool {
|
||||
(self.start <= item) && (item < self.end)
|
||||
|
|
@ -163,11 +161,9 @@ impl<Idx: PartialOrd<Idx>> RangeFrom<Idx> {
|
|||
/// ```
|
||||
/// #![feature(range_contains)]
|
||||
///
|
||||
/// # fn main() {
|
||||
/// assert!(!(3..).contains(2));
|
||||
/// assert!( (3..).contains(3));
|
||||
/// assert!( (3..).contains(1_000_000_000));
|
||||
/// # }
|
||||
/// ```
|
||||
pub fn contains(&self, item: Idx) -> bool {
|
||||
(self.start <= item)
|
||||
|
|
@ -191,6 +187,8 @@ impl<Idx: PartialOrd<Idx>> RangeFrom<Idx> {
|
|||
/// a `for` loop directly. This won't compile:
|
||||
///
|
||||
/// ```compile_fail,E0277
|
||||
/// // error[E0277]: the trait bound `std::ops::RangeTo<{integer}>:
|
||||
/// // std::iter::Iterator` is not satisfied
|
||||
/// for i in ..5 {
|
||||
/// // ...
|
||||
/// }
|
||||
|
|
@ -234,11 +232,9 @@ impl<Idx: PartialOrd<Idx>> RangeTo<Idx> {
|
|||
/// ```
|
||||
/// #![feature(range_contains)]
|
||||
///
|
||||
/// # fn main() {
|
||||
/// assert!( (..5).contains(-1_000_000_000));
|
||||
/// assert!( (..5).contains(4));
|
||||
/// assert!(!(..5).contains(5));
|
||||
/// # }
|
||||
/// ```
|
||||
pub fn contains(&self, item: Idx) -> bool {
|
||||
(item < self.end)
|
||||
|
|
@ -255,14 +251,12 @@ impl<Idx: PartialOrd<Idx>> RangeTo<Idx> {
|
|||
/// ```
|
||||
/// #![feature(inclusive_range,inclusive_range_syntax)]
|
||||
///
|
||||
/// # fn main() {
|
||||
/// assert_eq!((3...5), std::ops::RangeInclusive { start: 3, end: 5 });
|
||||
/// assert_eq!(3 + 4 + 5, (3...5).sum());
|
||||
///
|
||||
/// let arr = [0, 1, 2, 3];
|
||||
/// assert_eq!(arr[ ...2], [0,1,2 ]);
|
||||
/// assert_eq!(arr[1...2], [ 1,2 ]); // RangeInclusive
|
||||
/// # }
|
||||
/// ```
|
||||
#[derive(Clone, PartialEq, Eq, Hash)] // not Copy -- see #27186
|
||||
#[unstable(feature = "inclusive_range", reason = "recently added, follows RFC", issue = "28237")]
|
||||
|
|
@ -295,7 +289,6 @@ impl<Idx: PartialOrd<Idx>> RangeInclusive<Idx> {
|
|||
/// ```
|
||||
/// #![feature(range_contains,inclusive_range_syntax)]
|
||||
///
|
||||
/// # fn main() {
|
||||
/// assert!(!(3...5).contains(2));
|
||||
/// assert!( (3...5).contains(3));
|
||||
/// assert!( (3...5).contains(4));
|
||||
|
|
@ -304,7 +297,6 @@ impl<Idx: PartialOrd<Idx>> RangeInclusive<Idx> {
|
|||
///
|
||||
/// assert!( (3...3).contains(3));
|
||||
/// assert!(!(3...2).contains(3));
|
||||
/// # }
|
||||
/// ```
|
||||
pub fn contains(&self, item: Idx) -> bool {
|
||||
self.start <= item && item <= self.end
|
||||
|
|
@ -330,6 +322,9 @@ impl<Idx: PartialOrd<Idx>> RangeInclusive<Idx> {
|
|||
///
|
||||
/// ```compile_fail,E0277
|
||||
/// #![feature(inclusive_range_syntax)]
|
||||
///
|
||||
/// // error[E0277]: the trait bound `std::ops::RangeToInclusive<{integer}>:
|
||||
/// // std::iter::Iterator` is not satisfied
|
||||
/// for i in ...5 {
|
||||
/// // ...
|
||||
/// }
|
||||
|
|
@ -341,11 +336,9 @@ impl<Idx: PartialOrd<Idx>> RangeInclusive<Idx> {
|
|||
/// ```
|
||||
/// #![feature(inclusive_range_syntax)]
|
||||
///
|
||||
/// # fn main() {
|
||||
/// let arr = [0, 1, 2, 3];
|
||||
/// assert_eq!(arr[ ...2], [0,1,2 ]); // RangeToInclusive
|
||||
/// assert_eq!(arr[1...2], [ 1,2 ]);
|
||||
/// # }
|
||||
/// ```
|
||||
///
|
||||
/// [`IntoIterator`]: ../iter/trait.Iterator.html
|
||||
|
|
@ -377,11 +370,9 @@ impl<Idx: PartialOrd<Idx>> RangeToInclusive<Idx> {
|
|||
/// ```
|
||||
/// #![feature(range_contains,inclusive_range_syntax)]
|
||||
///
|
||||
/// # fn main() {
|
||||
/// assert!( (...5).contains(-1_000_000_000));
|
||||
/// assert!( (...5).contains(5));
|
||||
/// assert!(!(...5).contains(6));
|
||||
/// # }
|
||||
/// ```
|
||||
pub fn contains(&self, item: Idx) -> bool {
|
||||
(item <= self.end)
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue