1use crate::marker::Tuple;
2
3/// The version of the call operator that takes an immutable receiver.
4///
5/// Instances of `Fn` can be called repeatedly without mutating state.
6///
7/// *This trait (`Fn`) is not to be confused with [function pointers]
8/// (`fn`).*
9///
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.
15///
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`]
18/// is expected.
19///
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.
24///
25/// See the [chapter on closures in *The Rust Programming Language*][book] for
26/// some more information on this topic.
27///
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].
31///
32/// [book]: ../../book/ch13-01-closures.html
33/// [function pointers]: fn
34/// [nomicon]: ../../nomicon/hrtb.html
35///
36/// # Examples
37///
38/// ## Calling a closure
39///
40/// ```
41/// let square = |x| x * x;
42/// assert_eq!(square(5), 25);
43/// ```
44///
45/// ## Using a `Fn` parameter
46///
47/// ```
48/// fn call_with_one<F>(func: F) -> usize
49/// where F: Fn(usize) -> usize {
50/// func(1)
51/// }
52///
53/// let double = |x| x * 2;
54/// assert_eq!(call_with_one(double), 2);
55/// ```
56#[lang = "fn"]
57#[stable(feature = "rust1", since = "1.0.0")]
58#[rustc_paren_sugar]
59#[rustc_on_unimplemented(
60 on(
61 Args = "()",
62 note = "wrap the `{Self}` in a closure with no arguments: `|| {{ /* code */ }}`"
63 ),
64 on(
65 _Self = "unsafe fn",
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 */ }}`"
69 ),
70 message = "expected a `{Trait}` closure, found `{Self}`",
71 label = "expected an `{Trait}` closure, found `{Self}`"
72)]
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]
76pub 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;
80}
81
82/// The version of the call operator that takes a mutable receiver.
83///
84/// Instances of `FnMut` can be called repeatedly and may mutate state.
85///
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.
91///
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.
95///
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`].
100///
101/// See the [chapter on closures in *The Rust Programming Language*][book] for
102/// some more information on this topic.
103///
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].
107///
108/// [book]: ../../book/ch13-01-closures.html
109/// [function pointers]: fn
110/// [nomicon]: ../../nomicon/hrtb.html
111///
112/// # Examples
113///
114/// ## Calling a mutably capturing closure
115///
116/// ```
117/// let mut x = 5;
118/// {
119/// let mut square_x = || x *= x;
120/// square_x();
121/// }
122/// assert_eq!(x, 25);
123/// ```
124///
125/// ## Using a `FnMut` parameter
126///
127/// ```
128/// fn do_twice<F>(mut func: F)
129/// where F: FnMut()
130/// {
131/// func();
132/// func();
133/// }
134///
135/// let mut x: usize = 1;
136/// {
137/// let add_two_to_x = || x += 2;
138/// do_twice(add_two_to_x);
139/// }
140///
141/// assert_eq!(x, 5);
142/// ```
143#[lang = "fn_mut"]
144#[stable(feature = "rust1", since = "1.0.0")]
145#[rustc_paren_sugar]
146#[rustc_on_unimplemented(
147 on(
148 Args = "()",
149 note = "wrap the `{Self}` in a closure with no arguments: `|| {{ /* code */ }}`"
150 ),
151 on(
152 _Self = "unsafe fn",
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 */ }}`"
156 ),
157 message = "expected a `{Trait}` closure, found `{Self}`",
158 label = "expected an `{Trait}` closure, found `{Self}`"
159)]
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]
163pub 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;
167}
168
169/// The version of the call operator that takes a by-value receiver.
170///
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.
174///
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`]).
178///
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.
181///
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`].
186///
187/// See the [chapter on closures in *The Rust Programming Language*][book] for
188/// some more information on this topic.
189///
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].
193///
194/// [book]: ../../book/ch13-01-closures.html
195/// [function pointers]: fn
196/// [nomicon]: ../../nomicon/hrtb.html
197///
198/// # Examples
199///
200/// ## Using a `FnOnce` parameter
201///
202/// ```
203/// fn consume_with_relish<F>(func: F)
204/// where F: FnOnce() -> String
205/// {
206/// // `func` consumes its captured variables, so it cannot be run more
207/// // than once.
208/// println!("Consumed: {}", func());
209///
210/// println!("Delicious!");
211///
212/// // Attempting to invoke `func()` again will throw a `use of moved
213/// // value` error for `func`.
214/// }
215///
216/// let x = String::from("x");
217/// let consume_and_return_x = move || x;
218/// consume_with_relish(consume_and_return_x);
219///
220/// // `consume_and_return_x` can no longer be invoked at this point
221/// ```
222#[lang = "fn_once"]
223#[stable(feature = "rust1", since = "1.0.0")]
224#[rustc_paren_sugar]
225#[rustc_on_unimplemented(
226 on(
227 Args = "()",
228 note = "wrap the `{Self}` in a closure with no arguments: `|| {{ /* code */ }}`"
229 ),
230 on(
231 _Self = "unsafe fn",
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 */ }}`"
235 ),
236 message = "expected a `{Trait}` closure, found `{Self}`",
237 label = "expected an `{Trait}` closure, found `{Self}`"
238)]
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]
242pub 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")]
246 type Output;
247
248 /// Performs the call operation.
249 #[unstable(feature = "fn_traits", issue = "29625")]
250 extern "rust-call" fn call_once(self, args: Args) -> Self::Output;
251}
252
253mod impls {
254 use crate::marker::Tuple;
255
256 #[stable(feature = "rust1", since = "1.0.0")]
257 impl<A: Tuple, F: ?Sized> Fn<A> for &F
258 where
259 F: Fn<A>,
260 {
261 extern "rust-call" fn call(&self, args: A) -> F::Output {
262 (**self).call(args)
263 }
264 }
265
266 #[stable(feature = "rust1", since = "1.0.0")]
267 impl<A: Tuple, F: ?Sized> FnMut<A> for &F
268 where
269 F: Fn<A>,
270 {
271 extern "rust-call" fn call_mut(&mut self, args: A) -> F::Output {
272 (**self).call(args)
273 }
274 }
275
276 #[stable(feature = "rust1", since = "1.0.0")]
277 impl<A: Tuple, F: ?Sized> FnOnce<A> for &F
278 where
279 F: Fn<A>,
280 {
281 type Output = F::Output;
282
283 extern "rust-call" fn call_once(self, args: A) -> F::Output {
284 (*self).call(args)
285 }
286 }
287
288 #[stable(feature = "rust1", since = "1.0.0")]
289 impl<A: Tuple, F: ?Sized> FnMut<A> for &mut F
290 where
291 F: FnMut<A>,
292 {
293 extern "rust-call" fn call_mut(&mut self, args: A) -> F::Output {
294 (*self).call_mut(args)
295 }
296 }
297
298 #[stable(feature = "rust1", since = "1.0.0")]
299 impl<A: Tuple, F: ?Sized> FnOnce<A> for &mut F
300 where
301 F: FnMut<A>,
302 {
303 type Output = F::Output;
304 extern "rust-call" fn call_once(self, args: A) -> F::Output {
305 (*self).call_mut(args)
306 }
307 }
308}
309