1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
use crate::marker::Tuple;

/// 采用不可变接收者的调用运算符的版本。
///
/// `Fn` 的实例可以在不改变状态的情况下重复调用。
///
/// *请勿将此 trait (`Fn`) 与 [函数指针][function pointers] (`fn`) 混淆。*
///
/// `Fn` 是由闭包自动实现的,闭包只接受对捕获变量的不可变引用或根本不捕获任何东西,以及 (safe) [函数指针][function pointers] (有一些注意事项,请参见他们的文档以获取更多详细信息)。
///
/// 此外,对于实现 `Fn` 的任何类型 `F`,`&F` 也实现了 `Fn`。
///
/// 由于 [`FnMut`] 和 [`FnOnce`] 都是 `Fn` 的 supertraits,因此 `Fn` 的任何实例都可以用作参数,其中需要 [`FnMut`] 或 [`FnOnce`]。
///
/// 当您要接受类似函数类型的参数并且需要反复调用且不改变状态 (例如,同时调用它) 时,请使用 `Fn` 作为绑定。
/// 如果不需要严格的要求,请使用 [`FnMut`] 或 [`FnOnce`] 作为界限。
///
/// 有关此主题的更多信息,请参见 [Rust 编程语言][book] 中关于闭包的章节。
///
/// 还要注意的是 `Fn` traits 的特殊语法 (例如
/// `Fn(usize, bool) -> usize`)。对此技术细节感兴趣的人可以参考 [Rustonomicon 中的相关部分][nomicon]。
///
/// [book]: ../../book/ch13-01-closures.html
/// [function pointers]: fn
/// [nomicon]: ../../nomicon/hrtb.html
///
/// # Examples
///
/// ## 调用一个闭包
///
/// ```
/// let square = |x| x * x;
/// assert_eq!(square(5), 25);
/// ```
///
/// ## 使用 `Fn` 参数
///
/// ```
/// fn call_with_one<F>(func: F) -> usize
///     where F: Fn(usize) -> usize {
///     func(1)
/// }
///
/// let double = |x| x * 2;
/// assert_eq!(call_with_one(double), 2);
/// ```
///
///
///
///
///
///
///
///
///
#[lang = "fn"]
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_paren_sugar]
#[rustc_on_unimplemented(
    on(
        Args = "()",
        note = "wrap the `{Self}` in a closure with no arguments: `|| {{ /* code */ }}`"
    ),
    on(
        _Self = "unsafe fn",
        note = "unsafe function cannot be called generically without an unsafe block",
        // SAFETY: tidy 不够聪明,无法判断下面的 unsafe 块是字符串
        label = "call the function in a closure: `|| unsafe {{ /* code */ }}`"
    ),
    message = "expected a `{Fn}<{Args}>` closure, found `{Self}`",
    label = "expected an `Fn<{Args}>` closure, found `{Self}`"
)]
#[fundamental] // 这样 regex 可以依靠 `&str: !FnMut`
#[must_use = "closures are lazy and do nothing unless called"]
#[const_trait]
pub trait Fn<Args: Tuple>: FnMut<Args> {
    /// 执行调用操作。
    #[unstable(feature = "fn_traits", issue = "29625")]
    extern "rust-call" fn call(&self, args: Args) -> Self::Output;
}

/// 采用可变接收者的调用运算符的版本。
///
/// `FnMut` 的实例可以重复调用,并且可以改变状态。
///
/// `FnMut` 是由闭包自动实现的,闭包采用对捕获变量的可变引用,以及实现 [`Fn`] 的所有类型,例如 (safe) [函数指针][function pointers] (因为 `FnMut` 是 [`Fn`] 的 super trait)。
/// 另外,对于任何实现 `FnMut` 的 `F` 类型,`&mut F` 也实现 `FnMut`。
///
/// 由于 [`FnOnce`] 是 `FnMut` 的 super trait,因此可以在期望 [`FnOnce`] 的地方使用 `FnMut` 的任何实例,并且由于 [`Fn`] 是 `FnMut` 的子特性,因此可以在预期 `FnMut` 的地方使用 [`Fn`] 的任何实例。
///
/// 当您想接受类似函数类型的参数并需要反复调用它,同时允许其改变状态时,请使用 `FnMut` 作为绑定。
/// 如果您不希望参数改变状态,请使用 [`Fn`] 作为绑定; 如果不需要重复调用,请使用 [`FnOnce`]。
///
/// 有关此主题的更多信息,请参见 [Rust 编程语言][book] 中关于闭包的章节。
///
/// 还要注意的是 `Fn` traits 的特殊语法 (例如
/// `Fn(usize, bool) -> usize`)。对此技术细节感兴趣的人可以参考 [Rustonomicon 中的相关部分][nomicon]。
///
/// [book]: ../../book/ch13-01-closures.html
/// [function pointers]: fn
/// [nomicon]: ../../nomicon/hrtb.html
///
/// # Examples
///
/// ## 调用可变捕获闭包
///
/// ```
/// let mut x = 5;
/// {
///     let mut square_x = || x *= x;
///     square_x();
/// }
/// assert_eq!(x, 25);
/// ```
///
/// ## 使用 `FnMut` 参数
///
/// ```
/// fn do_twice<F>(mut func: F)
///     where F: FnMut()
/// {
///     func();
///     func();
/// }
///
/// let mut x: usize = 1;
/// {
///     let add_two_to_x = || x += 2;
///     do_twice(add_two_to_x);
/// }
///
/// assert_eq!(x, 5);
/// ```
///
///
///
///
///
///
///
///
///
#[lang = "fn_mut"]
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_paren_sugar]
#[rustc_on_unimplemented(
    on(
        Args = "()",
        note = "wrap the `{Self}` in a closure with no arguments: `|| {{ /* code */ }}`"
    ),
    on(
        _Self = "unsafe fn",
        note = "unsafe function cannot be called generically without an unsafe block",
        // SAFETY: tidy 不够聪明,无法判断下面的 unsafe 块是字符串
        label = "call the function in a closure: `|| unsafe {{ /* code */ }}`"
    ),
    message = "expected a `{FnMut}<{Args}>` closure, found `{Self}`",
    label = "expected an `FnMut<{Args}>` closure, found `{Self}`"
)]
#[fundamental] // 这样 regex 可以依靠 `&str: !FnMut`
#[must_use = "closures are lazy and do nothing unless called"]
#[const_trait]
pub trait FnMut<Args: Tuple>: FnOnce<Args> {
    /// 执行调用操作。
    #[unstable(feature = "fn_traits", issue = "29625")]
    extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output;
}

/// 具有按值接收者的调用运算符的版本。
///
/// 可以调用 `FnOnce` 的实例,但可能无法多次调用。因此,如果唯一知道类型的是它实现 `FnOnce`,则只能调用一次。
///
/// `FnOnce` 由可能消耗捕获的变量的闭包以及所有实现 [`FnMut`] 的类型自动实现,例如 (safe) [函数指针][function pointers] (因为 `FnOnce` 是 [`FnMut`] 的 super trait)。
///
///
/// 由于 [`Fn`] 和 [`FnMut`] 都是 `FnOnce` 的子特性,因此可以在期望使用 `FnOnce` 的情况下使用 [`Fn`] 或 [`FnMut`] 的任何实例。
///
/// 当您想接受类似函数类型的参数并且只需要调用一次时,可以使用 `FnOnce` 作为绑定。
/// 如果需要重复调用该参数,请使用 [`FnMut`] 作为界限; 如果还需要它不改变状态,请使用 [`Fn`]。
///
/// 有关此主题的更多信息,请参见 [Rust 编程语言][book] 中关于闭包的章节。
///
/// 还要注意的是 `Fn` traits 的特殊语法 (例如
/// `Fn(usize, bool) -> usize`)。对此技术细节感兴趣的人可以参考 [Rustonomicon 中的相关部分][nomicon]。
///
/// [book]: ../../book/ch13-01-closures.html
/// [function pointers]: fn
/// [nomicon]: ../../nomicon/hrtb.html
///
/// # Examples
///
/// ## 使用 `FnOnce` 参数
///
/// ```
/// fn consume_with_relish<F>(func: F)
///     where F: FnOnce() -> String
/// {
///     // `func` 消耗其捕获的变量,因此不能多次运行。
/////
///     println!("Consumed: {}", func());
///
///     println!("Delicious!");
///
///     // 再次尝试调用 `func()` 将为 `func` 引发 `use of moved value` 错误。
/////
/// }
///
/// let x = String::from("x");
/// let consume_and_return_x = move || x;
/// consume_with_relish(consume_and_return_x);
///
/// // 此时无法再调用 `consume_and_return_x`
/// ```
///
///
///
///
///
///
///
///
#[lang = "fn_once"]
#[stable(feature = "rust1", since = "1.0.0")]
#[rustc_paren_sugar]
#[rustc_on_unimplemented(
    on(
        Args = "()",
        note = "wrap the `{Self}` in a closure with no arguments: `|| {{ /* code */ }}`"
    ),
    on(
        _Self = "unsafe fn",
        note = "unsafe function cannot be called generically without an unsafe block",
        // SAFETY: tidy 不够聪明,无法判断下面的 unsafe 块是字符串
        label = "call the function in a closure: `|| unsafe {{ /* code */ }}`"
    ),
    message = "expected a `{FnOnce}<{Args}>` closure, found `{Self}`",
    label = "expected an `FnOnce<{Args}>` closure, found `{Self}`"
)]
#[fundamental] // 这样 regex 可以依靠 `&str: !FnMut`
#[must_use = "closures are lazy and do nothing unless called"]
#[const_trait]
pub trait FnOnce<Args: Tuple> {
    /// 使用调用运算符后的返回类型。
    #[lang = "fn_once_output"]
    #[stable(feature = "fn_once_output", since = "1.12.0")]
    type Output;

    /// 执行调用操作。
    #[unstable(feature = "fn_traits", issue = "29625")]
    extern "rust-call" fn call_once(self, args: Args) -> Self::Output;
}

mod impls {
    use crate::marker::Tuple;

    #[stable(feature = "rust1", since = "1.0.0")]
    impl<A: Tuple, F: ?Sized> Fn<A> for &F
    where
        F: Fn<A>,
    {
        extern "rust-call" fn call(&self, args: A) -> F::Output {
            (**self).call(args)
        }
    }

    #[stable(feature = "rust1", since = "1.0.0")]
    impl<A: Tuple, F: ?Sized> FnMut<A> for &F
    where
        F: Fn<A>,
    {
        extern "rust-call" fn call_mut(&mut self, args: A) -> F::Output {
            (**self).call(args)
        }
    }

    #[stable(feature = "rust1", since = "1.0.0")]
    impl<A: Tuple, F: ?Sized> FnOnce<A> for &F
    where
        F: Fn<A>,
    {
        type Output = F::Output;

        extern "rust-call" fn call_once(self, args: A) -> F::Output {
            (*self).call(args)
        }
    }

    #[stable(feature = "rust1", since = "1.0.0")]
    impl<A: Tuple, F: ?Sized> FnMut<A> for &mut F
    where
        F: FnMut<A>,
    {
        extern "rust-call" fn call_mut(&mut self, args: A) -> F::Output {
            (*self).call_mut(args)
        }
    }

    #[stable(feature = "rust1", since = "1.0.0")]
    impl<A: Tuple, F: ?Sized> FnOnce<A> for &mut F
    where
        F: FnMut<A>,
    {
        type Output = F::Output;
        extern "rust-call" fn call_once(self, args: A) -> F::Output {
            (*self).call_mut(args)
        }
    }
}