10
10
11
11
/// A version of the call operator that takes an immutable receiver.
12
12
///
13
- /// # Examples
13
+ /// Closures only taking immutable references to captured variables
14
+ /// automatically implement this trait, which allows them to be invoked.
15
+ /// For mutably referenced captures, see [`FnMut`], and for consuming the
16
+ /// capture, see [`FnOnce`].
17
+ ///
18
+ /// You can use the [`Fn`] traits when you want to accept a closure as a
19
+ /// parameter. Since both [`FnMut`] and [`FnOnce`] are supertraits of `Fn`, any
20
+ /// instance of `Fn` can be used where a [`FnMut`] or [`FnOnce`] is expected.
21
+ ///
22
+ /// See the [chapter on closures in *The Rust Programming Language*][book] for
23
+ /// more information about closures in general.
14
24
///
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`].
25
+ /// Also of note is the special syntax for `Fn` traits (e.g.
26
+ /// `Fn(usize, bool) -> usize`). Those interested in the technical details of
27
+ /// this can refer to [the relevant section in *The Rustonomicon*][nomicon].
19
28
///
29
+ /// [book]: ../../book/second-edition/ch13-01-closures.html
20
30
/// [`FnMut`]: trait.FnMut.html
21
31
/// [`FnOnce`]: trait.FnOnce.html
32
+ /// [nomicon]: ../../nomicon/hrtb.html
33
+ ///
34
+ /// # Examples
35
+ ///
36
+ /// ## Calling a closure
22
37
///
23
38
/// ```
24
39
/// let square = |x| x * x;
25
40
/// assert_eq!(square(5), 25);
26
41
/// ```
27
42
///
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`).
43
+ /// ## Using a `Fn` parameter
31
44
///
32
45
/// ```
33
46
/// fn call_with_one<F>(func: F) -> usize
43
56
#[ rustc_paren_sugar]
44
57
#[ fundamental] // so that regex can rely that `&str: !FnMut`
45
58
pub trait Fn < Args > : FnMut < Args > {
46
- /// This is called when the call operator is used .
59
+ /// Performs the call operation .
47
60
#[ unstable( feature = "fn_traits" , issue = "29625" ) ]
48
61
extern "rust-call" fn call ( & self , args : Args ) -> Self :: Output ;
49
62
}
50
63
51
64
/// A version of the call operator that takes a mutable receiver.
52
65
///
66
+ /// Closures that might mutably reference captured variables automatically
67
+ /// implement this trait, which allows them to be invoked. For immutably
68
+ /// referenced captures, see [`Fn`], and for consuming the captures, see
69
+ /// [`FnOnce`].
70
+ ///
71
+ /// You can use the [`Fn`] traits when you want to accept a closure as a
72
+ /// parameter. Since [`FnOnce`] is a supertrait of `FnMut`, any instance of
73
+ /// `FnMut` can be used where a [`FnOnce`] is expected, and since [`Fn`] is a
74
+ /// subtrait of `FnMut`, any instance of [`Fn`] can be used where [`FnMut`] is
75
+ /// expected.
76
+ ///
77
+ /// See the [chapter on closures in *The Rust Programming Language*][book] for
78
+ /// more information about closures in general.
79
+ ///
80
+ /// Also of note is the special syntax for `Fn` traits (e.g.
81
+ /// `Fn(usize, bool) -> usize`). Those interested in the technical details of
82
+ /// this can refer to [the relevant section in *The Rustonomicon*][nomicon].
83
+ ///
84
+ /// [book]: ../../book/second-edition/ch13-01-closures.html
85
+ /// [`Fn`]: trait.Fnhtml
86
+ /// [`FnOnce`]: trait.FnOnce.html
87
+ /// [nomicon]: ../../nomicon/hrtb.html
88
+ ///
53
89
/// # Examples
54
90
///
55
- /// Closures that mutably capture variables automatically implement this trait,
56
- /// which allows them to be invoked.
91
+ /// ## Calling a mutably capturing closure
57
92
///
58
93
/// ```
59
94
/// let mut x = 5;
@@ -64,8 +99,7 @@ pub trait Fn<Args> : FnMut<Args> {
64
99
/// assert_eq!(x, 25);
65
100
/// ```
66
101
///
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`).
102
+ /// ## Using a `FnMut` parameter
69
103
///
70
104
/// ```
71
105
/// fn do_twice<F>(mut func: F)
@@ -88,39 +122,58 @@ pub trait Fn<Args> : FnMut<Args> {
88
122
#[ rustc_paren_sugar]
89
123
#[ fundamental] // so that regex can rely that `&str: !FnMut`
90
124
pub trait FnMut < Args > : FnOnce < Args > {
91
- /// This is called when the call operator is used .
125
+ /// Performs the call operation .
92
126
#[ unstable( feature = "fn_traits" , issue = "29625" ) ]
93
127
extern "rust-call" fn call_mut ( & mut self , args : Args ) -> Self :: Output ;
94
128
}
95
129
96
130
/// A version of the call operator that takes a by-value receiver.
97
131
///
132
+ /// Closures that might take ownership of captured variables automatically
133
+ /// implement this trait, which allows them to be invoked. For immutably
134
+ /// referenced captures, see [`Fn`], and for mutably referenced captures,
135
+ /// see [`FnMut`].
136
+ ///
137
+ /// You can use the [`Fn`] traits when you want to accept a closure as a
138
+ /// parameter. Since both [`Fn`] and [`FnMut`] are subtraits of `FnOnce`, any
139
+ /// instance of [`Fn`] or [`FnMut`] can be used where a `FnOnce` is expected.
140
+ ///
141
+ /// See the [chapter on closures in *The Rust Programming Language*][book] for
142
+ /// more information about closures in general.
143
+ ///
144
+ /// Also of note is the special syntax for `Fn` traits (e.g.
145
+ /// `Fn(usize, bool) -> usize`). Those interested in the technical details of
146
+ /// this can refer to [the relevant section in *The Rustonomicon*][nomicon].
147
+ ///
148
+ /// [book]: ../../book/second-edition/ch13-01-closures.html
149
+ /// [`Fn`]: trait.Fn.html
150
+ /// [`FnMut`]: trait.FnMut.html
151
+ /// [nomicon]: ../../nomicon/hrtb.html
152
+ ///
98
153
/// # Examples
99
154
///
100
- /// By-value closures automatically implement this trait, which allows them to
101
- /// be invoked.
155
+ /// ## Calling a by-value closure
102
156
///
103
157
/// ```
104
158
/// let x = 5;
105
159
/// let square_x = move || x * x;
106
160
/// assert_eq!(square_x(), 25);
107
161
/// ```
108
162
///
109
- /// By-value Closures can also be passed to higher-level functions through a
110
- /// `FnOnce` parameter.
163
+ /// ## Using a `FnOnce` parameter
111
164
///
112
165
/// ```
113
166
/// fn consume_with_relish<F>(func: F)
114
167
/// where F: FnOnce() -> String
115
168
/// {
116
169
/// // `func` consumes its captured variables, so it cannot be run more
117
- /// // than once
170
+ /// // than once.
118
171
/// println!("Consumed: {}", func());
119
172
///
120
173
/// println!("Delicious!");
121
174
///
122
175
/// // Attempting to invoke `func()` again will throw a `use of moved
123
- /// // value` error for `func`
176
+ /// // value` error for `func`.
124
177
/// }
125
178
///
126
179
/// let x = String::from("x");
@@ -138,7 +191,7 @@ pub trait FnOnce<Args> {
138
191
#[ stable( feature = "fn_once_output" , since = "1.12.0" ) ]
139
192
type Output ;
140
193
141
- /// This is called when the call operator is used .
194
+ /// Performs the call operation .
142
195
#[ unstable( feature = "fn_traits" , issue = "29625" ) ]
143
196
extern "rust-call" fn call_once ( self , args : Args ) -> Self :: Output ;
144
197
}
0 commit comments