Trait std::ops::FnOnce1.0.0[][src]

#[must_use = "closures are lazy and do nothing unless called"]
pub trait FnOnce<Args> {
    type Output;
    extern "rust-call" fn call_once(self, args: Args) -> Self::Output;
}
Expand description

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 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.

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
Run

Associated Types

type Output1.12.0[src]

Expand description

The returned type after the call operator is used.

Required methods

extern "rust-call" fn call_once(self, args: Args) -> Self::Output[src]

🔬 This is a nightly-only experimental API. (fn_traits #29625)
Expand description

Performs the call operation.

Implementors

impl<'_, A, F> FnOnce<A> for &'_ F where
    F: Fn<A> + ?Sized
[src]

type Output = <F as FnOnce<A>>::Output

pub extern "rust-call" fn call_once(
    self,
    args: A
) -> <F as FnOnce<A>>::Output
[src]

🔬 This is a nightly-only experimental API. (fn_traits #29625)

impl<'_, A, F> FnOnce<A> for &'_ mut F where
    F: FnMut<A> + ?Sized
[src]

type Output = <F as FnOnce<A>>::Output

pub extern "rust-call" fn call_once(
    self,
    args: A
) -> <F as FnOnce<A>>::Output
[src]

🔬 This is a nightly-only experimental API. (fn_traits #29625)

impl<Args, F, A> FnOnce<Args> for Box<F, A> where
    F: FnOnce<Args> + ?Sized,
    A: Allocator
1.35.0[src]

type Output = <F as FnOnce<Args>>::Output

pub extern "rust-call" fn call_once(
    self,
    args: Args
) -> <Box<F, A> as FnOnce<Args>>::Output

Notable traits for Box<F, A>

impl<F, A> Future for Box<F, A> where
    F: Future + Unpin + ?Sized,
    A: Allocator + 'static, 
type Output = <F as Future>::Output;impl<I, A> Iterator for Box<I, A> where
    I: Iterator + ?Sized,
    A: Allocator
type Item = <I as Iterator>::Item;impl<R: Read + ?Sized> Read for Box<R>impl<W: Write + ?Sized> Write for Box<W>
[src]

🔬 This is a nightly-only experimental API. (fn_traits #29625)

impl<R, F: FnOnce() -> R> FnOnce() for AssertUnwindSafe<F>1.9.0[src]

type Output = R

extern "rust-call" fn call_once(self, _args: ()) -> R[src]

🔬 This is a nightly-only experimental API. (fn_traits #29625)