core::ops::FnOnce - Rust
Description: API documentation for the Rust `FnOnce` trait in crate `core`.
Keywords: rust, rustlang, rust-lang, FnOnce

# Trait core::ops::FnOnce 1.0.0 [−] [src]

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

## Calling a by-value closure

    let x = 5;
    let square_x = move || x * x;
    assert_eq!(square_x(), 25);Run

## 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 pointRun

## Associated Types

### `type Output`
1.12.0

The returned type after the call operator is used.

## Required Methods

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

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

Performs the call operation.

## Implementors

- `impl<'a, A, F: ?Sized> FnOnce<A> for &'a F where
  F: Fn<A>, type Output = F::Output;`
- `impl<'a, A, F: ?Sized> FnOnce<A> for &'a mut F where
  F: FnMut<A>, type Output = F::Output;`

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result
+
  Collapse/expand all sections

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)