mirror of
https://github.com/rust-lang/rust
synced 2024-10-17 22:13:59 +00:00
Enforce Tuple trait on Fn traits
This commit is contained in:
parent
6b8d9dd0a0
commit
2786acce98
|
@ -158,6 +158,8 @@
|
||||||
#[cfg(not(no_global_oom_handling))]
|
#[cfg(not(no_global_oom_handling))]
|
||||||
use core::iter::FromIterator;
|
use core::iter::FromIterator;
|
||||||
use core::iter::{FusedIterator, Iterator};
|
use core::iter::{FusedIterator, Iterator};
|
||||||
|
#[cfg(not(bootstrap))]
|
||||||
|
use core::marker::Tuple;
|
||||||
use core::marker::{Destruct, Unpin, Unsize};
|
use core::marker::{Destruct, Unpin, Unsize};
|
||||||
use core::mem;
|
use core::mem;
|
||||||
use core::ops::{
|
use core::ops::{
|
||||||
|
@ -1979,6 +1981,7 @@ fn is_empty(&self) -> bool {
|
||||||
#[stable(feature = "fused", since = "1.26.0")]
|
#[stable(feature = "fused", since = "1.26.0")]
|
||||||
impl<I: FusedIterator + ?Sized, A: Allocator> FusedIterator for Box<I, A> {}
|
impl<I: FusedIterator + ?Sized, A: Allocator> FusedIterator for Box<I, A> {}
|
||||||
|
|
||||||
|
#[cfg(bootstrap)]
|
||||||
#[stable(feature = "boxed_closure_impls", since = "1.35.0")]
|
#[stable(feature = "boxed_closure_impls", since = "1.35.0")]
|
||||||
impl<Args, F: FnOnce<Args> + ?Sized, A: Allocator> FnOnce<Args> for Box<F, A> {
|
impl<Args, F: FnOnce<Args> + ?Sized, A: Allocator> FnOnce<Args> for Box<F, A> {
|
||||||
type Output = <F as FnOnce<Args>>::Output;
|
type Output = <F as FnOnce<Args>>::Output;
|
||||||
|
@ -1988,6 +1991,17 @@ extern "rust-call" fn call_once(self, args: Args) -> Self::Output {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[cfg(not(bootstrap))]
|
||||||
|
#[stable(feature = "boxed_closure_impls", since = "1.35.0")]
|
||||||
|
impl<Args: Tuple, F: FnOnce<Args> + ?Sized, A: Allocator> FnOnce<Args> for Box<F, A> {
|
||||||
|
type Output = <F as FnOnce<Args>>::Output;
|
||||||
|
|
||||||
|
extern "rust-call" fn call_once(self, args: Args) -> Self::Output {
|
||||||
|
<F as FnOnce<Args>>::call_once(*self, args)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[cfg(bootstrap)]
|
||||||
#[stable(feature = "boxed_closure_impls", since = "1.35.0")]
|
#[stable(feature = "boxed_closure_impls", since = "1.35.0")]
|
||||||
impl<Args, F: FnMut<Args> + ?Sized, A: Allocator> FnMut<Args> for Box<F, A> {
|
impl<Args, F: FnMut<Args> + ?Sized, A: Allocator> FnMut<Args> for Box<F, A> {
|
||||||
extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output {
|
extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output {
|
||||||
|
@ -1995,6 +2009,15 @@ extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[cfg(not(bootstrap))]
|
||||||
|
#[stable(feature = "boxed_closure_impls", since = "1.35.0")]
|
||||||
|
impl<Args: Tuple, F: FnMut<Args> + ?Sized, A: Allocator> FnMut<Args> for Box<F, A> {
|
||||||
|
extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output {
|
||||||
|
<F as FnMut<Args>>::call_mut(self, args)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
#[cfg(bootstrap)]
|
||||||
#[stable(feature = "boxed_closure_impls", since = "1.35.0")]
|
#[stable(feature = "boxed_closure_impls", since = "1.35.0")]
|
||||||
impl<Args, F: Fn<Args> + ?Sized, A: Allocator> Fn<Args> for Box<F, A> {
|
impl<Args, F: Fn<Args> + ?Sized, A: Allocator> Fn<Args> for Box<F, A> {
|
||||||
extern "rust-call" fn call(&self, args: Args) -> Self::Output {
|
extern "rust-call" fn call(&self, args: Args) -> Self::Output {
|
||||||
|
@ -2002,6 +2025,14 @@ extern "rust-call" fn call(&self, args: Args) -> Self::Output {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[cfg(not(bootstrap))]
|
||||||
|
#[stable(feature = "boxed_closure_impls", since = "1.35.0")]
|
||||||
|
impl<Args: Tuple, F: Fn<Args> + ?Sized, A: Allocator> Fn<Args> for Box<F, A> {
|
||||||
|
extern "rust-call" fn call(&self, args: Args) -> Self::Output {
|
||||||
|
<F as Fn<Args>>::call(self, args)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
#[unstable(feature = "coerce_unsized", issue = "27732")]
|
#[unstable(feature = "coerce_unsized", issue = "27732")]
|
||||||
impl<T: ?Sized + Unsize<U>, U: ?Sized, A: Allocator> CoerceUnsized<Box<U, A>> for Box<T, A> {}
|
impl<T: ?Sized + Unsize<U>, U: ?Sized, A: Allocator> CoerceUnsized<Box<U, A>> for Box<T, A> {}
|
||||||
|
|
||||||
|
|
|
@ -150,6 +150,7 @@
|
||||||
#![feature(trusted_len)]
|
#![feature(trusted_len)]
|
||||||
#![feature(trusted_random_access)]
|
#![feature(trusted_random_access)]
|
||||||
#![feature(try_trait_v2)]
|
#![feature(try_trait_v2)]
|
||||||
|
#![cfg_attr(not(bootstrap), feature(tuple_trait))]
|
||||||
#![feature(unchecked_math)]
|
#![feature(unchecked_math)]
|
||||||
#![feature(unicode_internals)]
|
#![feature(unicode_internals)]
|
||||||
#![feature(unsize)]
|
#![feature(unsize)]
|
||||||
|
|
|
@ -55,6 +55,8 @@
|
||||||
#![allow(missing_docs)]
|
#![allow(missing_docs)]
|
||||||
|
|
||||||
use crate::marker::DiscriminantKind;
|
use crate::marker::DiscriminantKind;
|
||||||
|
#[cfg(not(bootstrap))]
|
||||||
|
use crate::marker::Tuple;
|
||||||
use crate::mem;
|
use crate::mem;
|
||||||
|
|
||||||
// These imports are used for simplifying intra-doc links
|
// These imports are used for simplifying intra-doc links
|
||||||
|
@ -2169,11 +2171,75 @@ pub unsafe fn drop_in_place<T: ?Sized>(to_drop: *mut T) {
|
||||||
/// `unreachable_unchecked` is actually being reached. The bug is in *crate A*,
|
/// `unreachable_unchecked` is actually being reached. The bug is in *crate A*,
|
||||||
/// which violates the principle that a `const fn` must behave the same at
|
/// which violates the principle that a `const fn` must behave the same at
|
||||||
/// compile-time and at run-time. The unsafe code in crate B is fine.
|
/// compile-time and at run-time. The unsafe code in crate B is fine.
|
||||||
|
#[cfg(bootstrap)]
|
||||||
#[rustc_const_unstable(feature = "const_eval_select", issue = "none")]
|
#[rustc_const_unstable(feature = "const_eval_select", issue = "none")]
|
||||||
pub fn const_eval_select<ARG, F, G, RET>(arg: ARG, called_in_const: F, called_at_rt: G) -> RET
|
pub fn const_eval_select<ARG, F, G, RET>(arg: ARG, called_in_const: F, called_at_rt: G) -> RET
|
||||||
where
|
where
|
||||||
G: FnOnce<ARG, Output = RET>,
|
G: FnOnce<ARG, Output = RET>,
|
||||||
F: FnOnce<ARG, Output = RET>;
|
F: FnOnce<ARG, Output = RET>;
|
||||||
|
|
||||||
|
/// Selects which function to call depending on the context.
|
||||||
|
///
|
||||||
|
/// If this function is evaluated at compile-time, then a call to this
|
||||||
|
/// intrinsic will be replaced with a call to `called_in_const`. It gets
|
||||||
|
/// replaced with a call to `called_at_rt` otherwise.
|
||||||
|
///
|
||||||
|
/// # Type Requirements
|
||||||
|
///
|
||||||
|
/// The two functions must be both function items. They cannot be function
|
||||||
|
/// pointers or closures. The first function must be a `const fn`.
|
||||||
|
///
|
||||||
|
/// `arg` will be the tupled arguments that will be passed to either one of
|
||||||
|
/// the two functions, therefore, both functions must accept the same type of
|
||||||
|
/// arguments. Both functions must return RET.
|
||||||
|
///
|
||||||
|
/// # Safety
|
||||||
|
///
|
||||||
|
/// The two functions must behave observably equivalent. Safe code in other
|
||||||
|
/// crates may assume that calling a `const fn` at compile-time and at run-time
|
||||||
|
/// produces the same result. A function that produces a different result when
|
||||||
|
/// evaluated at run-time, or has any other observable side-effects, is
|
||||||
|
/// *unsound*.
|
||||||
|
///
|
||||||
|
/// Here is an example of how this could cause a problem:
|
||||||
|
/// ```no_run
|
||||||
|
/// #![feature(const_eval_select)]
|
||||||
|
/// #![feature(core_intrinsics)]
|
||||||
|
/// use std::hint::unreachable_unchecked;
|
||||||
|
/// use std::intrinsics::const_eval_select;
|
||||||
|
///
|
||||||
|
/// // Crate A
|
||||||
|
/// pub const fn inconsistent() -> i32 {
|
||||||
|
/// fn runtime() -> i32 { 1 }
|
||||||
|
/// const fn compiletime() -> i32 { 2 }
|
||||||
|
///
|
||||||
|
/// unsafe {
|
||||||
|
// // ⚠ This code violates the required equivalence of `compiletime`
|
||||||
|
/// // and `runtime`.
|
||||||
|
/// const_eval_select((), compiletime, runtime)
|
||||||
|
/// }
|
||||||
|
/// }
|
||||||
|
///
|
||||||
|
/// // Crate B
|
||||||
|
/// const X: i32 = inconsistent();
|
||||||
|
/// let x = inconsistent();
|
||||||
|
/// if x != X { unsafe { unreachable_unchecked(); }}
|
||||||
|
/// ```
|
||||||
|
///
|
||||||
|
/// This code causes Undefined Behavior when being run, since the
|
||||||
|
/// `unreachable_unchecked` is actually being reached. The bug is in *crate A*,
|
||||||
|
/// which violates the principle that a `const fn` must behave the same at
|
||||||
|
/// compile-time and at run-time. The unsafe code in crate B is fine.
|
||||||
|
#[cfg(not(bootstrap))]
|
||||||
|
#[rustc_const_unstable(feature = "const_eval_select", issue = "none")]
|
||||||
|
pub fn const_eval_select<ARG: Tuple, F, G, RET>(
|
||||||
|
arg: ARG,
|
||||||
|
called_in_const: F,
|
||||||
|
called_at_rt: G,
|
||||||
|
) -> RET
|
||||||
|
where
|
||||||
|
G: FnOnce<ARG, Output = RET>,
|
||||||
|
F: FnOnce<ARG, Output = RET>;
|
||||||
}
|
}
|
||||||
|
|
||||||
// Some functions are defined here because they accidentally got made
|
// Some functions are defined here because they accidentally got made
|
||||||
|
|
|
@ -1,3 +1,6 @@
|
||||||
|
#[cfg(not(bootstrap))]
|
||||||
|
use crate::marker::Tuple;
|
||||||
|
|
||||||
/// The version of the call operator that takes an immutable receiver.
|
/// The version of the call operator that takes an immutable receiver.
|
||||||
///
|
///
|
||||||
/// Instances of `Fn` can be called repeatedly without mutating state.
|
/// Instances of `Fn` can be called repeatedly without mutating state.
|
||||||
|
@ -51,6 +54,7 @@
|
||||||
/// let double = |x| x * 2;
|
/// let double = |x| x * 2;
|
||||||
/// assert_eq!(call_with_one(double), 2);
|
/// assert_eq!(call_with_one(double), 2);
|
||||||
/// ```
|
/// ```
|
||||||
|
#[cfg(bootstrap)]
|
||||||
#[lang = "fn"]
|
#[lang = "fn"]
|
||||||
#[stable(feature = "rust1", since = "1.0.0")]
|
#[stable(feature = "rust1", since = "1.0.0")]
|
||||||
#[rustc_diagnostic_item = "Fn"]
|
#[rustc_diagnostic_item = "Fn"]
|
||||||
|
@ -78,6 +82,87 @@ pub trait Fn<Args>: FnMut<Args> {
|
||||||
extern "rust-call" fn call(&self, args: Args) -> Self::Output;
|
extern "rust-call" fn call(&self, args: Args) -> Self::Output;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// The version of the call operator that takes an immutable receiver.
|
||||||
|
///
|
||||||
|
/// Instances of `Fn` can be called repeatedly without mutating state.
|
||||||
|
///
|
||||||
|
/// *This trait (`Fn`) is not to be confused with [function pointers]
|
||||||
|
/// (`fn`).*
|
||||||
|
///
|
||||||
|
/// `Fn` is implemented automatically by closures which only take immutable
|
||||||
|
/// references to captured variables or don't capture anything at all, as well
|
||||||
|
/// as (safe) [function pointers] (with some caveats, see their documentation
|
||||||
|
/// for more details). Additionally, for any type `F` that implements `Fn`, `&F`
|
||||||
|
/// implements `Fn`, too.
|
||||||
|
///
|
||||||
|
/// Since both [`FnMut`] and [`FnOnce`] are supertraits of `Fn`, any
|
||||||
|
/// instance of `Fn` can be used as a parameter where a [`FnMut`] or [`FnOnce`]
|
||||||
|
/// is expected.
|
||||||
|
///
|
||||||
|
/// Use `Fn` as a bound when you want to accept a parameter of function-like
|
||||||
|
/// type and need to call it repeatedly and without mutating state (e.g., when
|
||||||
|
/// calling it concurrently). If you do not need such strict requirements, use
|
||||||
|
/// [`FnMut`] or [`FnOnce`] as bounds.
|
||||||
|
///
|
||||||
|
/// See the [chapter on closures in *The Rust Programming Language*][book] for
|
||||||
|
/// some more information on this topic.
|
||||||
|
///
|
||||||
|
/// Also of note is the special syntax for `Fn` traits (e.g.
|
||||||
|
/// `Fn(usize, bool) -> usize`). Those interested in the technical details of
|
||||||
|
/// this can refer to [the relevant section in the *Rustonomicon*][nomicon].
|
||||||
|
///
|
||||||
|
/// [book]: ../../book/ch13-01-closures.html
|
||||||
|
/// [function pointers]: fn
|
||||||
|
/// [nomicon]: ../../nomicon/hrtb.html
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ## Calling a closure
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// let square = |x| x * x;
|
||||||
|
/// assert_eq!(square(5), 25);
|
||||||
|
/// ```
|
||||||
|
///
|
||||||
|
/// ## Using a `Fn` parameter
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// 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);
|
||||||
|
/// ```
|
||||||
|
#[cfg(not(bootstrap))]
|
||||||
|
#[lang = "fn"]
|
||||||
|
#[stable(feature = "rust1", since = "1.0.0")]
|
||||||
|
#[rustc_diagnostic_item = "Fn"]
|
||||||
|
#[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 is not smart enough to tell that the below unsafe block is a string
|
||||||
|
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] // so that regex can rely that `&str: !FnMut`
|
||||||
|
#[must_use = "closures are lazy and do nothing unless called"]
|
||||||
|
#[const_trait]
|
||||||
|
pub trait Fn<Args: Tuple>: FnMut<Args> {
|
||||||
|
/// Performs the call operation.
|
||||||
|
#[unstable(feature = "fn_traits", issue = "29625")]
|
||||||
|
extern "rust-call" fn call(&self, args: Args) -> Self::Output;
|
||||||
|
}
|
||||||
|
|
||||||
/// The version of the call operator that takes a mutable receiver.
|
/// The version of the call operator that takes a mutable receiver.
|
||||||
///
|
///
|
||||||
/// Instances of `FnMut` can be called repeatedly and may mutate state.
|
/// Instances of `FnMut` can be called repeatedly and may mutate state.
|
||||||
|
@ -139,6 +224,7 @@ pub trait Fn<Args>: FnMut<Args> {
|
||||||
///
|
///
|
||||||
/// assert_eq!(x, 5);
|
/// assert_eq!(x, 5);
|
||||||
/// ```
|
/// ```
|
||||||
|
#[cfg(bootstrap)]
|
||||||
#[lang = "fn_mut"]
|
#[lang = "fn_mut"]
|
||||||
#[stable(feature = "rust1", since = "1.0.0")]
|
#[stable(feature = "rust1", since = "1.0.0")]
|
||||||
#[rustc_diagnostic_item = "FnMut"]
|
#[rustc_diagnostic_item = "FnMut"]
|
||||||
|
@ -166,6 +252,95 @@ pub trait FnMut<Args>: FnOnce<Args> {
|
||||||
extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output;
|
extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// The version of the call operator that takes a mutable receiver.
|
||||||
|
///
|
||||||
|
/// Instances of `FnMut` can be called repeatedly and may mutate state.
|
||||||
|
///
|
||||||
|
/// `FnMut` is implemented automatically by closures which take mutable
|
||||||
|
/// references to captured variables, as well as all types that implement
|
||||||
|
/// [`Fn`], e.g., (safe) [function pointers] (since `FnMut` is a supertrait of
|
||||||
|
/// [`Fn`]). Additionally, for any type `F` that implements `FnMut`, `&mut F`
|
||||||
|
/// implements `FnMut`, too.
|
||||||
|
///
|
||||||
|
/// Since [`FnOnce`] is a supertrait of `FnMut`, any instance of `FnMut` can be
|
||||||
|
/// used where a [`FnOnce`] is expected, and since [`Fn`] is a subtrait of
|
||||||
|
/// `FnMut`, any instance of [`Fn`] can be used where `FnMut` is expected.
|
||||||
|
///
|
||||||
|
/// Use `FnMut` as a bound when you want to accept a parameter of function-like
|
||||||
|
/// type and need to call it repeatedly, while allowing it to mutate state.
|
||||||
|
/// If you don't want the parameter to mutate state, use [`Fn`] as a
|
||||||
|
/// bound; if you don't need to call it repeatedly, use [`FnOnce`].
|
||||||
|
///
|
||||||
|
/// See the [chapter on closures in *The Rust Programming Language*][book] for
|
||||||
|
/// some more information on this topic.
|
||||||
|
///
|
||||||
|
/// Also of note is the special syntax for `Fn` traits (e.g.
|
||||||
|
/// `Fn(usize, bool) -> usize`). Those interested in the technical details of
|
||||||
|
/// this can refer to [the relevant section in the *Rustonomicon*][nomicon].
|
||||||
|
///
|
||||||
|
/// [book]: ../../book/ch13-01-closures.html
|
||||||
|
/// [function pointers]: fn
|
||||||
|
/// [nomicon]: ../../nomicon/hrtb.html
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ## Calling a mutably capturing closure
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// let mut x = 5;
|
||||||
|
/// {
|
||||||
|
/// let mut square_x = || x *= x;
|
||||||
|
/// square_x();
|
||||||
|
/// }
|
||||||
|
/// assert_eq!(x, 25);
|
||||||
|
/// ```
|
||||||
|
///
|
||||||
|
/// ## Using a `FnMut` parameter
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// 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);
|
||||||
|
/// ```
|
||||||
|
#[cfg(not(bootstrap))]
|
||||||
|
#[lang = "fn_mut"]
|
||||||
|
#[stable(feature = "rust1", since = "1.0.0")]
|
||||||
|
#[rustc_diagnostic_item = "FnMut"]
|
||||||
|
#[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 is not smart enough to tell that the below unsafe block is a string
|
||||||
|
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] // so that regex can rely that `&str: !FnMut`
|
||||||
|
#[must_use = "closures are lazy and do nothing unless called"]
|
||||||
|
#[const_trait]
|
||||||
|
pub trait FnMut<Args: Tuple>: FnOnce<Args> {
|
||||||
|
/// Performs the call operation.
|
||||||
|
#[unstable(feature = "fn_traits", issue = "29625")]
|
||||||
|
extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output;
|
||||||
|
}
|
||||||
|
|
||||||
/// The version of the call operator that takes a by-value receiver.
|
/// The version of the call operator that takes a by-value receiver.
|
||||||
///
|
///
|
||||||
/// Instances of `FnOnce` can be called, but might not be callable multiple
|
/// Instances of `FnOnce` can be called, but might not be callable multiple
|
||||||
|
@ -219,6 +394,7 @@ pub trait FnMut<Args>: FnOnce<Args> {
|
||||||
///
|
///
|
||||||
/// // `consume_and_return_x` can no longer be invoked at this point
|
/// // `consume_and_return_x` can no longer be invoked at this point
|
||||||
/// ```
|
/// ```
|
||||||
|
#[cfg(bootstrap)]
|
||||||
#[lang = "fn_once"]
|
#[lang = "fn_once"]
|
||||||
#[stable(feature = "rust1", since = "1.0.0")]
|
#[stable(feature = "rust1", since = "1.0.0")]
|
||||||
#[rustc_diagnostic_item = "FnOnce"]
|
#[rustc_diagnostic_item = "FnOnce"]
|
||||||
|
@ -251,6 +427,93 @@ pub trait FnOnce<Args> {
|
||||||
extern "rust-call" fn call_once(self, args: Args) -> Self::Output;
|
extern "rust-call" fn call_once(self, args: Args) -> Self::Output;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/// The version of the call operator that takes a by-value receiver.
|
||||||
|
///
|
||||||
|
/// Instances of `FnOnce` can be called, but might not be callable multiple
|
||||||
|
/// times. Because of this, if the only thing known about a type is that it
|
||||||
|
/// implements `FnOnce`, it can only be called once.
|
||||||
|
///
|
||||||
|
/// `FnOnce` is implemented automatically by closures that might consume captured
|
||||||
|
/// variables, as well as all types that implement [`FnMut`], e.g., (safe)
|
||||||
|
/// [function pointers] (since `FnOnce` is a supertrait of [`FnMut`]).
|
||||||
|
///
|
||||||
|
/// Since both [`Fn`] and [`FnMut`] are subtraits of `FnOnce`, any instance of
|
||||||
|
/// [`Fn`] or [`FnMut`] can be used where a `FnOnce` is expected.
|
||||||
|
///
|
||||||
|
/// Use `FnOnce` as a bound when you want to accept a parameter of function-like
|
||||||
|
/// type and only need to call it once. If you need to call the parameter
|
||||||
|
/// repeatedly, use [`FnMut`] as a bound; if you also need it to not mutate
|
||||||
|
/// state, use [`Fn`].
|
||||||
|
///
|
||||||
|
/// See the [chapter on closures in *The Rust Programming Language*][book] for
|
||||||
|
/// some more information on this topic.
|
||||||
|
///
|
||||||
|
/// Also of note is the special syntax for `Fn` traits (e.g.
|
||||||
|
/// `Fn(usize, bool) -> usize`). Those interested in the technical details of
|
||||||
|
/// this can refer to [the relevant section in the *Rustonomicon*][nomicon].
|
||||||
|
///
|
||||||
|
/// [book]: ../../book/ch13-01-closures.html
|
||||||
|
/// [function pointers]: fn
|
||||||
|
/// [nomicon]: ../../nomicon/hrtb.html
|
||||||
|
///
|
||||||
|
/// # Examples
|
||||||
|
///
|
||||||
|
/// ## Using a `FnOnce` parameter
|
||||||
|
///
|
||||||
|
/// ```
|
||||||
|
/// fn consume_with_relish<F>(func: F)
|
||||||
|
/// where F: FnOnce() -> String
|
||||||
|
/// {
|
||||||
|
/// // `func` consumes its captured variables, so it cannot be run more
|
||||||
|
/// // than once.
|
||||||
|
/// println!("Consumed: {}", func());
|
||||||
|
///
|
||||||
|
/// println!("Delicious!");
|
||||||
|
///
|
||||||
|
/// // Attempting to invoke `func()` again will throw a `use of moved
|
||||||
|
/// // value` error for `func`.
|
||||||
|
/// }
|
||||||
|
///
|
||||||
|
/// let x = String::from("x");
|
||||||
|
/// let consume_and_return_x = move || x;
|
||||||
|
/// consume_with_relish(consume_and_return_x);
|
||||||
|
///
|
||||||
|
/// // `consume_and_return_x` can no longer be invoked at this point
|
||||||
|
/// ```
|
||||||
|
#[cfg(not(bootstrap))]
|
||||||
|
#[lang = "fn_once"]
|
||||||
|
#[stable(feature = "rust1", since = "1.0.0")]
|
||||||
|
#[rustc_diagnostic_item = "FnOnce"]
|
||||||
|
#[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 is not smart enough to tell that the below unsafe block is a string
|
||||||
|
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] // so that regex can rely that `&str: !FnMut`
|
||||||
|
#[must_use = "closures are lazy and do nothing unless called"]
|
||||||
|
#[const_trait]
|
||||||
|
pub trait FnOnce<Args: Tuple> {
|
||||||
|
/// The returned type after the call operator is used.
|
||||||
|
#[lang = "fn_once_output"]
|
||||||
|
#[stable(feature = "fn_once_output", since = "1.12.0")]
|
||||||
|
type Output;
|
||||||
|
|
||||||
|
/// Performs the call operation.
|
||||||
|
#[unstable(feature = "fn_traits", issue = "29625")]
|
||||||
|
extern "rust-call" fn call_once(self, args: Args) -> Self::Output;
|
||||||
|
}
|
||||||
|
|
||||||
|
#[cfg(bootstrap)]
|
||||||
mod impls {
|
mod impls {
|
||||||
#[stable(feature = "rust1", since = "1.0.0")]
|
#[stable(feature = "rust1", since = "1.0.0")]
|
||||||
#[rustc_const_unstable(feature = "const_fn_trait_ref_impls", issue = "101803")]
|
#[rustc_const_unstable(feature = "const_fn_trait_ref_impls", issue = "101803")]
|
||||||
|
@ -310,3 +573,61 @@ extern "rust-call" fn call_once(self, args: A) -> F::Output {
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
|
|
||||||
|
#[cfg(not(bootstrap))]
|
||||||
|
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)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
Loading…
Reference in a new issue