]>
git.proxmox.com Git - rustc.git/blob - library/core/src/ops/function.rs
1 use crate::marker
::Tuple
;
3 /// The version of the call operator that takes an immutable receiver.
5 /// Instances of `Fn` can be called repeatedly without mutating state.
7 /// *This trait (`Fn`) is not to be confused with [function pointers]
10 /// `Fn` is implemented automatically by closures which only take immutable
11 /// references to captured variables or don't capture anything at all, as well
12 /// as (safe) [function pointers] (with some caveats, see their documentation
13 /// for more details). Additionally, for any type `F` that implements `Fn`, `&F`
14 /// implements `Fn`, too.
16 /// Since both [`FnMut`] and [`FnOnce`] are supertraits of `Fn`, any
17 /// instance of `Fn` can be used as a parameter where a [`FnMut`] or [`FnOnce`]
20 /// Use `Fn` as a bound when you want to accept a parameter of function-like
21 /// type and need to call it repeatedly and without mutating state (e.g., when
22 /// calling it concurrently). If you do not need such strict requirements, use
23 /// [`FnMut`] or [`FnOnce`] as bounds.
25 /// See the [chapter on closures in *The Rust Programming Language*][book] for
26 /// some more information on this topic.
28 /// Also of note is the special syntax for `Fn` traits (e.g.
29 /// `Fn(usize, bool) -> usize`). Those interested in the technical details of
30 /// this can refer to [the relevant section in the *Rustonomicon*][nomicon].
32 /// [book]: ../../book/ch13-01-closures.html
33 /// [function pointers]: fn
34 /// [nomicon]: ../../nomicon/hrtb.html
38 /// ## Calling a closure
41 /// let square = |x| x * x;
42 /// assert_eq!(square(5), 25);
45 /// ## Using a `Fn` parameter
48 /// fn call_with_one<F>(func: F) -> usize
49 /// where F: Fn(usize) -> usize {
53 /// let double = |x| x * 2;
54 /// assert_eq!(call_with_one(double), 2);
57 #[stable(feature = "rust1", since = "1.0.0")]
59 #[rustc_on_unimplemented(
62 note
= "wrap the `{Self}` in a closure with no arguments: `|| {{ /* code */ }}`"
66 note
= "unsafe function cannot be called generically without an unsafe block",
67 // SAFETY: tidy is not smart enough to tell that the below unsafe block is a string
68 label
= "call the function in a closure: `|| unsafe {{ /* code */ }}`"
70 message
= "expected a `{Trait}` closure, found `{Self}`",
71 label
= "expected an `{Trait}` closure, found `{Self}`"
73 #[fundamental] // so that regex can rely that `&str: !FnMut`
74 #[must_use = "closures are lazy and do nothing unless called"]
75 // FIXME(effects) #[const_trait]
76 pub trait Fn
<Args
: Tuple
>: FnMut
<Args
> {
77 /// Performs the call operation.
78 #[unstable(feature = "fn_traits", issue = "29625")]
79 extern "rust-call" fn call(&self, args
: Args
) -> Self::Output
;
82 /// The version of the call operator that takes a mutable receiver.
84 /// Instances of `FnMut` can be called repeatedly and may mutate state.
86 /// `FnMut` is implemented automatically by closures which take mutable
87 /// references to captured variables, as well as all types that implement
88 /// [`Fn`], e.g., (safe) [function pointers] (since `FnMut` is a supertrait of
89 /// [`Fn`]). Additionally, for any type `F` that implements `FnMut`, `&mut F`
90 /// implements `FnMut`, too.
92 /// Since [`FnOnce`] is a supertrait of `FnMut`, any instance of `FnMut` can be
93 /// used where a [`FnOnce`] is expected, and since [`Fn`] is a subtrait of
94 /// `FnMut`, any instance of [`Fn`] can be used where `FnMut` is expected.
96 /// Use `FnMut` as a bound when you want to accept a parameter of function-like
97 /// type and need to call it repeatedly, while allowing it to mutate state.
98 /// If you don't want the parameter to mutate state, use [`Fn`] as a
99 /// bound; if you don't need to call it repeatedly, use [`FnOnce`].
101 /// See the [chapter on closures in *The Rust Programming Language*][book] for
102 /// some more information on this topic.
104 /// Also of note is the special syntax for `Fn` traits (e.g.
105 /// `Fn(usize, bool) -> usize`). Those interested in the technical details of
106 /// this can refer to [the relevant section in the *Rustonomicon*][nomicon].
108 /// [book]: ../../book/ch13-01-closures.html
109 /// [function pointers]: fn
110 /// [nomicon]: ../../nomicon/hrtb.html
114 /// ## Calling a mutably capturing closure
119 /// let mut square_x = || x *= x;
122 /// assert_eq!(x, 25);
125 /// ## Using a `FnMut` parameter
128 /// fn do_twice<F>(mut func: F)
135 /// let mut x: usize = 1;
137 /// let add_two_to_x = || x += 2;
138 /// do_twice(add_two_to_x);
141 /// assert_eq!(x, 5);
144 #[stable(feature = "rust1", since = "1.0.0")]
146 #[rustc_on_unimplemented(
149 note
= "wrap the `{Self}` in a closure with no arguments: `|| {{ /* code */ }}`"
153 note
= "unsafe function cannot be called generically without an unsafe block",
154 // SAFETY: tidy is not smart enough to tell that the below unsafe block is a string
155 label
= "call the function in a closure: `|| unsafe {{ /* code */ }}`"
157 message
= "expected a `{Trait}` closure, found `{Self}`",
158 label
= "expected an `{Trait}` closure, found `{Self}`"
160 #[fundamental] // so that regex can rely that `&str: !FnMut`
161 #[must_use = "closures are lazy and do nothing unless called"]
162 // FIXME(effects) #[const_trait]
163 pub trait FnMut
<Args
: Tuple
>: FnOnce
<Args
> {
164 /// Performs the call operation.
165 #[unstable(feature = "fn_traits", issue = "29625")]
166 extern "rust-call" fn call_mut(&mut self, args
: Args
) -> Self::Output
;
169 /// The version of the call operator that takes a by-value receiver.
171 /// Instances of `FnOnce` can be called, but might not be callable multiple
172 /// times. Because of this, if the only thing known about a type is that it
173 /// implements `FnOnce`, it can only be called once.
175 /// `FnOnce` is implemented automatically by closures that might consume captured
176 /// variables, as well as all types that implement [`FnMut`], e.g., (safe)
177 /// [function pointers] (since `FnOnce` is a supertrait of [`FnMut`]).
179 /// Since both [`Fn`] and [`FnMut`] are subtraits of `FnOnce`, any instance of
180 /// [`Fn`] or [`FnMut`] can be used where a `FnOnce` is expected.
182 /// Use `FnOnce` as a bound when you want to accept a parameter of function-like
183 /// type and only need to call it once. If you need to call the parameter
184 /// repeatedly, use [`FnMut`] as a bound; if you also need it to not mutate
185 /// state, use [`Fn`].
187 /// See the [chapter on closures in *The Rust Programming Language*][book] for
188 /// some more information on this topic.
190 /// Also of note is the special syntax for `Fn` traits (e.g.
191 /// `Fn(usize, bool) -> usize`). Those interested in the technical details of
192 /// this can refer to [the relevant section in the *Rustonomicon*][nomicon].
194 /// [book]: ../../book/ch13-01-closures.html
195 /// [function pointers]: fn
196 /// [nomicon]: ../../nomicon/hrtb.html
200 /// ## Using a `FnOnce` parameter
203 /// fn consume_with_relish<F>(func: F)
204 /// where F: FnOnce() -> String
206 /// // `func` consumes its captured variables, so it cannot be run more
208 /// println!("Consumed: {}", func());
210 /// println!("Delicious!");
212 /// // Attempting to invoke `func()` again will throw a `use of moved
213 /// // value` error for `func`.
216 /// let x = String::from("x");
217 /// let consume_and_return_x = move || x;
218 /// consume_with_relish(consume_and_return_x);
220 /// // `consume_and_return_x` can no longer be invoked at this point
223 #[stable(feature = "rust1", since = "1.0.0")]
225 #[rustc_on_unimplemented(
228 note
= "wrap the `{Self}` in a closure with no arguments: `|| {{ /* code */ }}`"
232 note
= "unsafe function cannot be called generically without an unsafe block",
233 // SAFETY: tidy is not smart enough to tell that the below unsafe block is a string
234 label
= "call the function in a closure: `|| unsafe {{ /* code */ }}`"
236 message
= "expected a `{Trait}` closure, found `{Self}`",
237 label
= "expected an `{Trait}` closure, found `{Self}`"
239 #[fundamental] // so that regex can rely that `&str: !FnMut`
240 #[must_use = "closures are lazy and do nothing unless called"]
241 // FIXME(effects) #[const_trait]
242 pub trait FnOnce
<Args
: Tuple
> {
243 /// The returned type after the call operator is used.
244 #[lang = "fn_once_output"]
245 #[stable(feature = "fn_once_output", since = "1.12.0")]
248 /// Performs the call operation.
249 #[unstable(feature = "fn_traits", issue = "29625")]
250 extern "rust-call" fn call_once(self, args
: Args
) -> Self::Output
;
254 use crate::marker
::Tuple
;
256 #[stable(feature = "rust1", since = "1.0.0")]
257 impl<A
: Tuple
, F
: ?Sized
> Fn
<A
> for &F
261 extern "rust-call" fn call(&self, args
: A
) -> F
::Output
{
266 #[stable(feature = "rust1", since = "1.0.0")]
267 impl<A
: Tuple
, F
: ?Sized
> FnMut
<A
> for &F
271 extern "rust-call" fn call_mut(&mut self, args
: A
) -> F
::Output
{
276 #[stable(feature = "rust1", since = "1.0.0")]
277 impl<A
: Tuple
, F
: ?Sized
> FnOnce
<A
> for &F
281 type Output
= F
::Output
;
283 extern "rust-call" fn call_once(self, args
: A
) -> F
::Output
{
288 #[stable(feature = "rust1", since = "1.0.0")]
289 impl<A
: Tuple
, F
: ?Sized
> FnMut
<A
> for &mut F
293 extern "rust-call" fn call_mut(&mut self, args
: A
) -> F
::Output
{
294 (*self).call_mut(args
)
298 #[stable(feature = "rust1", since = "1.0.0")]
299 impl<A
: Tuple
, F
: ?Sized
> FnOnce
<A
> for &mut F
303 type Output
= F
::Output
;
304 extern "rust-call" fn call_once(self, args
: A
) -> F
::Output
{
305 (*self).call_mut(args
)