Trait nom::lib::std::prelude::v1::v1::FnOnce

#[lang = "fn_once"]
#[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;
}

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

Associated Types

type Output

The returned type after the call operator is used.

Loading content...

Required methods

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

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

Performs the call operation.

Loading content...

Implementations on Foreign Types

impl<R, F> FnOnce() for AssertUnwindSafe<F> where
    F: FnOnce() -> R, 

type Output = R

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

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

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

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

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

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

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

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

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

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

Loading content...

Implementors

impl<A, F> FnOnce<A> for Box<F> where
    F: FnOnce<A> + ?Sized, 

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

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

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

Loading content...