diff --git a/src/libcore/ops/arith.rs b/src/libcore/ops/arith.rs index 97fd8651b047..62007caedd3f 100644 --- a/src/libcore/ops/arith.rs +++ b/src/libcore/ops/arith.rs @@ -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`, which permits +/// Note that `RHS` is `Self` by default, but this is not mandatory. For +/// example, [`std::time::SystemTime`] implements `Add`, 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`, which permits +/// Note that `RHS` is `Self` by default, but this is not mandatory. For +/// example, [`std::time::SystemTime`] implements `Sub`, 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 diff --git a/src/libcore/ops/bit.rs b/src/libcore/ops/bit.rs index e6fadf616b02..0bc5e554cb34 100644 --- a/src/libcore/ops/bit.rs +++ b/src/libcore/ops/bit.rs @@ -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`. diff --git a/src/libcore/ops/deref.rs b/src/libcore/ops/deref.rs index ac5ff1556f4d..a2e7c44cb249 100644 --- a/src/libcore/ops/deref.rs +++ b/src/libcore/ops/deref.rs @@ -111,7 +111,7 @@ impl<'a, T: ?Sized> Deref for &'a mut T { /// /// # More on `Deref` coercion /// -/// If `T` implements `MutDeref`, and `x` is a value of type `T`, +/// If `T` implements `DerefMut`, and `x` is a value of type `T`, /// then: /// * In mutable contexts, `*x` on non-pointer types is equivalent to /// `*Deref::deref(&x)`. diff --git a/src/libcore/ops/function.rs b/src/libcore/ops/function.rs index 5a61e9b68b86..2cc4e72817ff 100644 --- a/src/libcore/ops/function.rs +++ b/src/libcore/ops/function.rs @@ -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 : FnMut { 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 : FnOnce { 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 diff --git a/src/libcore/ops/index.rs b/src/libcore/ops/index.rs index 0652421511aa..d65c0aba5048 100644 --- a/src/libcore/ops/index.rs +++ b/src/libcore/ops/index.rs @@ -77,11 +77,9 @@ pub trait Index { /// `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 /// diff --git a/src/libcore/ops/range.rs b/src/libcore/ops/range.rs index 6a405cfdb980..463a50491a86 100644 --- a/src/libcore/ops/range.rs +++ b/src/libcore/ops/range.rs @@ -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> Range { /// ``` /// #![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> Range { /// /// 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> RangeFrom { /// ``` /// #![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> RangeFrom { /// 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> RangeTo { /// ``` /// #![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> RangeTo { /// ``` /// #![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> RangeInclusive { /// ``` /// #![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> RangeInclusive { /// /// 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> RangeInclusive { /// /// ```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> RangeInclusive { /// ``` /// #![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> RangeToInclusive { /// ``` /// #![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)