diff options
| -rw-r--r-- | src/libcore/ops/function.rs | 95 |
1 files changed, 74 insertions, 21 deletions
diff --git a/src/libcore/ops/function.rs b/src/libcore/ops/function.rs index 62bf69336a3..5a61e9b68b8 100644 --- a/src/libcore/ops/function.rs +++ b/src/libcore/ops/function.rs @@ -10,24 +10,37 @@ /// A version of the call operator that takes an immutable receiver. /// -/// # Examples +/// 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`]. +/// +/// 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. +/// +/// See the [chapter on closures in *The Rust Programming Language*][book] for +/// more information about closures in general. /// -/// Closures automatically implement this trait, which allows them to be -/// invoked. Note, however, that `Fn` takes an immutable reference to any -/// captured variables. To take a mutable capture, implement [`FnMut`], and to -/// consume the capture, implement [`FnOnce`]. +/// 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]. /// +/// [book]: ../../book/second-edition/ch13-01-closures.html /// [`FnMut`]: trait.FnMut.html /// [`FnOnce`]: trait.FnOnce.html +/// [nomicon]: ../../nomicon/hrtb.html +/// +/// # Examples +/// +/// ## Calling a closure /// /// ``` /// let square = |x| x * x; /// assert_eq!(square(5), 25); /// ``` /// -/// Closures can also be passed to higher-level functions through a `Fn` -/// parameter (or a `FnMut` or `FnOnce` parameter, which are supertraits of -/// `Fn`). +/// ## Using a `Fn` parameter /// /// ``` /// fn call_with_one<F>(func: F) -> usize @@ -43,17 +56,39 @@ #[rustc_paren_sugar] #[fundamental] // so that regex can rely that `&str: !FnMut` pub trait Fn<Args> : FnMut<Args> { - /// This is called when the call operator is used. + /// Performs the call operation. #[unstable(feature = "fn_traits", issue = "29625")] extern "rust-call" fn call(&self, args: Args) -> Self::Output; } /// A 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`]. +/// +/// 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. +/// +/// See the [chapter on closures in *The Rust Programming Language*][book] for +/// more information about closures in general. +/// +/// 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]. +/// +/// [book]: ../../book/second-edition/ch13-01-closures.html +/// [`Fn`]: trait.Fnhtml +/// [`FnOnce`]: trait.FnOnce.html +/// [nomicon]: ../../nomicon/hrtb.html +/// /// # Examples /// -/// Closures that mutably capture variables automatically implement this trait, -/// which allows them to be invoked. +/// ## Calling a mutably capturing closure /// /// ``` /// let mut x = 5; @@ -64,8 +99,7 @@ pub trait Fn<Args> : FnMut<Args> { /// assert_eq!(x, 25); /// ``` /// -/// Closures can also be passed to higher-level functions through a `FnMut` -/// parameter (or a `FnOnce` parameter, which is a supertrait of `FnMut`). +/// ## Using a `FnMut` parameter /// /// ``` /// fn do_twice<F>(mut func: F) @@ -88,17 +122,37 @@ pub trait Fn<Args> : FnMut<Args> { #[rustc_paren_sugar] #[fundamental] // so that regex can rely that `&str: !FnMut` pub trait FnMut<Args> : FnOnce<Args> { - /// This is called when the call operator is used. + /// Performs the call operation. #[unstable(feature = "fn_traits", issue = "29625")] extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output; } /// A 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`]. +/// +/// 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. +/// +/// See the [chapter on closures in *The Rust Programming Language*][book] for +/// more information about closures in general. +/// +/// 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]. +/// +/// [book]: ../../book/second-edition/ch13-01-closures.html +/// [`Fn`]: trait.Fn.html +/// [`FnMut`]: trait.FnMut.html +/// [nomicon]: ../../nomicon/hrtb.html +/// /// # Examples /// -/// By-value closures automatically implement this trait, which allows them to -/// be invoked. +/// ## Calling a by-value closure /// /// ``` /// let x = 5; @@ -106,21 +160,20 @@ pub trait FnMut<Args> : FnOnce<Args> { /// assert_eq!(square_x(), 25); /// ``` /// -/// By-value Closures can also be passed to higher-level functions through a -/// `FnOnce` parameter. +/// ## Using a `FnOnce` parameter /// /// ``` /// fn consume_with_relish<F>(func: F) /// where F: FnOnce() -> String /// { /// // `func` consumes its captured variables, so it cannot be run more -/// // than once +/// // than once. /// println!("Consumed: {}", func()); /// /// println!("Delicious!"); /// /// // Attempting to invoke `func()` again will throw a `use of moved -/// // value` error for `func` +/// // value` error for `func`. /// } /// /// let x = String::from("x"); @@ -138,7 +191,7 @@ pub trait FnOnce<Args> { #[stable(feature = "fn_once_output", since = "1.12.0")] type Output; - /// This is called when the call operator is used. + /// Performs the call operation. #[unstable(feature = "fn_traits", issue = "29625")] extern "rust-call" fn call_once(self, args: Args) -> Self::Output; } |