src/libcore/ops/function.rs

   1 // Copyright 2012 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 /// A version of the call operator that takes an immutable receiver.
  12 ///
  13 /// # Examples
  14 ///
  15 /// Closures automatically implement this trait, which allows them to be
  16 /// invoked. Note, however, that `Fn` takes an immutable reference to any
  17 /// captured variables. To take a mutable capture, implement [`FnMut`], and to
  18 /// consume the capture, implement [`FnOnce`].
  19 ///
  20 /// [`FnMut`]: trait.FnMut.html
  21 /// [`FnOnce`]: trait.FnOnce.html
  22 ///
  23 /// ```
  24 /// let square = |x| x * x;
  25 /// assert_eq!(square(5), 25);
  26 /// ```
  27 ///
  28 /// Closures can also be passed to higher-level functions through a `Fn`
  29 /// parameter (or a `FnMut` or `FnOnce` parameter, which are supertraits of
  30 /// `Fn`).
  31 ///
  32 /// ```
  33 /// fn call_with_one<F>(func: F) -> usize
  34 ///     where F: Fn(usize) -> usize {
  35 ///     func(1)
  36 /// }
  37 ///
  38 /// let double = |x| x * 2;
  39 /// assert_eq!(call_with_one(double), 2);
  40 /// ```
  41 #[lang = "fn"]
  42 #[stable(feature = "rust1", since = "1.0.0")]
  43 #[rustc_paren_sugar]
  44 #[fundamental] // so that regex can rely that `&str: !FnMut`
  45 pub trait Fn<Args> : FnMut<Args> {
  46     /// This is called when the call operator is used.
  47     #[unstable(feature = "fn_traits", issue = "29625")]
  48     extern "rust-call" fn call(&self, args: Args) -> Self::Output;
  49 }
  50
  51 /// A version of the call operator that takes a mutable receiver.
  52 ///
  53 /// # Examples
  54 ///
  55 /// Closures that mutably capture variables automatically implement this trait,
  56 /// which allows them to be invoked.
  57 ///
  58 /// ```
  59 /// let mut x = 5;
  60 /// {
  61 ///     let mut square_x = || x *= x;
  62 ///     square_x();
  63 /// }
  64 /// assert_eq!(x, 25);
  65 /// ```
  66 ///
  67 /// Closures can also be passed to higher-level functions through a `FnMut`
  68 /// parameter (or a `FnOnce` parameter, which is a supertrait of `FnMut`).
  69 ///
  70 /// ```
  71 /// fn do_twice<F>(mut func: F)
  72 ///     where F: FnMut()
  73 /// {
  74 ///     func();
  75 ///     func();
  76 /// }
  77 ///
  78 /// let mut x: usize = 1;
  79 /// {
  80 ///     let add_two_to_x = || x += 2;
  81 ///     do_twice(add_two_to_x);
  82 /// }
  83 ///
  84 /// assert_eq!(x, 5);
  85 /// ```
  86 #[lang = "fn_mut"]
  87 #[stable(feature = "rust1", since = "1.0.0")]
  88 #[rustc_paren_sugar]
  89 #[fundamental] // so that regex can rely that `&str: !FnMut`
  90 pub trait FnMut<Args> : FnOnce<Args> {
  91     /// This is called when the call operator is used.
  92     #[unstable(feature = "fn_traits", issue = "29625")]
  93     extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output;
  94 }
  95
  96 /// A version of the call operator that takes a by-value receiver.
  97 ///
  98 /// # Examples
  99 ///
 100 /// By-value closures automatically implement this trait, which allows them to
 101 /// be invoked.
 102 ///
 103 /// ```
 104 /// let x = 5;
 105 /// let square_x = move || x * x;
 106 /// assert_eq!(square_x(), 25);
 107 /// ```
 108 ///
 109 /// By-value Closures can also be passed to higher-level functions through a
 110 /// `FnOnce` parameter.
 111 ///
 112 /// ```
 113 /// fn consume_with_relish<F>(func: F)
 114 ///     where F: FnOnce() -> String
 115 /// {
 116 ///     // `func` consumes its captured variables, so it cannot be run more
 117 ///     // than once
 118 ///     println!("Consumed: {}", func());
 119 ///
 120 ///     println!("Delicious!");
 121 ///
 122 ///     // Attempting to invoke `func()` again will throw a `use of moved
 123 ///     // value` error for `func`
 124 /// }
 125 ///
 126 /// let x = String::from("x");
 127 /// let consume_and_return_x = move || x;
 128 /// consume_with_relish(consume_and_return_x);
 129 ///
 130 /// // `consume_and_return_x` can no longer be invoked at this point
 131 /// ```
 132 #[lang = "fn_once"]
 133 #[stable(feature = "rust1", since = "1.0.0")]
 134 #[rustc_paren_sugar]
 135 #[fundamental] // so that regex can rely that `&str: !FnMut`
 136 pub trait FnOnce<Args> {
 137     /// The returned type after the call operator is used.
 138     #[stable(feature = "fn_once_output", since = "1.12.0")]
 139     type Output;
 140
 141     /// This is called when the call operator is used.
 142     #[unstable(feature = "fn_traits", issue = "29625")]
 143     extern "rust-call" fn call_once(self, args: Args) -> Self::Output;
 144 }
 145
 146 mod impls {
 147     #[stable(feature = "rust1", since = "1.0.0")]
 148     impl<'a,A,F:?Sized> Fn<A> for &'a F
 149         where F : Fn<A>
 150     {
 151         extern "rust-call" fn call(&self, args: A) -> F::Output {
 152             (**self).call(args)
 153         }
 154     }
 155
 156     #[stable(feature = "rust1", since = "1.0.0")]
 157     impl<'a,A,F:?Sized> FnMut<A> for &'a F
 158         where F : Fn<A>
 159     {
 160         extern "rust-call" fn call_mut(&mut self, args: A) -> F::Output {
 161             (**self).call(args)
 162         }
 163     }
 164
 165     #[stable(feature = "rust1", since = "1.0.0")]
 166     impl<'a,A,F:?Sized> FnOnce<A> for &'a F
 167         where F : Fn<A>
 168     {
 169         type Output = F::Output;
 170
 171         extern "rust-call" fn call_once(self, args: A) -> F::Output {
 172             (*self).call(args)
 173         }
 174     }
 175
 176     #[stable(feature = "rust1", since = "1.0.0")]
 177     impl<'a,A,F:?Sized> FnMut<A> for &'a mut F
 178         where F : FnMut<A>
 179     {
 180         extern "rust-call" fn call_mut(&mut self, args: A) -> F::Output {
 181             (*self).call_mut(args)
 182         }
 183     }
 184
 185     #[stable(feature = "rust1", since = "1.0.0")]
 186     impl<'a,A,F:?Sized> FnOnce<A> for &'a mut F
 187         where F : FnMut<A>
 188     {
 189         type Output = F::Output;
 190         extern "rust-call" fn call_once(self, args: A) -> F::Output {
 191             (*self).call_mut(args)
 192         }
 193     }
 194 }