# Primitive Type fn

1.0.0 ·
Expand description

Function pointers, like `fn(usize) -> bool`.

See also the traits `Fn`, `FnMut`, and `FnOnce`.

Function pointers are pointers that point to code, not data. They can be called just like functions. Like references, function pointers are, among other things, assumed to not be null, so if you want to pass a function pointer over FFI and be able to accommodate null pointers, make your type `Option<fn()>` with your required signature.

#### Safety

Plain function pointers are obtained by casting either plain functions, or closures that don’t capture an environment:

    fn add_one(x: usize) -> usize {
        x + 1
    }

    let ptr: fn(usize) -> usize = add_one;
    assert_eq!(ptr(5), 6);

    let clos: fn(usize) -> usize = |x| x + 5;
    assert_eq!(clos(5), 10);

Run

In addition to varying based on their signature, function pointers come in two flavors: safe and unsafe. Plain `fn()` function pointers can only point to safe functions, while `unsafe fn()` function pointers can point to safe or unsafe functions.

    fn add_one(x: usize) -> usize {
        x + 1
    }

    unsafe fn add_one_unsafely(x: usize) -> usize {
        x + 1
    }

    let safe_ptr: fn(usize) -> usize = add_one;

    //ERROR: mismatched types: expected normal fn, found unsafe fn
    //let bad_ptr: fn(usize) -> usize = add_one_unsafely;

    let unsafe_ptr: unsafe fn(usize) -> usize = add_one_unsafely;
    let really_safe_ptr: unsafe fn(usize) -> usize = add_one;

Run

#### ABI

On top of that, function pointers can vary based on what ABI they use. This is achieved by adding the `extern` keyword before the type, followed by the ABI in question. The default ABI is “Rust”, i.e., `fn()` is the exact same type as `extern "Rust" fn()`. A pointer to a function with C ABI would have type `extern "C" fn()`.

`extern "ABI" { ... }` blocks declare functions with ABI “ABI”. The default here is “C”, i.e., functions declared in an `extern {...}` block have “C” ABI.

For more information and a list of supported ABIs, see the nomicon’s section on foreign calling conventions.

#### Variadic functions

Extern function declarations with the “C” or “cdecl” ABIs can also be variadic, allowing them to be called with a variable number of arguments. Normal Rust functions, even those with an `extern "ABI"`, cannot be variadic. For more information, see the nomicon’s section on variadic functions.

#### Creating function pointers

When `bar` is the name of a function, then the expression `bar` is not a function pointer. Rather, it denotes a value of an unnameable type that uniquely identifies the function `bar`. The value is zero-sized because the type already identifies the function. This has the advantage that “calling” the value (it implements the `Fn*` traits) does not require dynamic dispatch.

This zero-sized type coerces to a regular function pointer. For example:

    use std::mem;

    fn bar(x: i32) {}

    let not_bar_ptr = bar; // `not_bar_ptr` is zero-sized, uniquely identifying `bar`
    assert_eq!(mem::size_of_val(&not_bar_ptr), 0);

    let bar_ptr: fn(i32) = not_bar_ptr; // force coercion to function pointer
    assert_eq!(mem::size_of_val(&bar_ptr), mem::size_of::<usize>());

    let footgun = &bar; // this is a shared reference to the zero-sized type identifying `bar`

Run

The last line shows that `&bar` is not a function pointer either. Rather, it is a reference to the function-specific ZST. `&bar` is basically never what you want when `bar` is a function.

#### Casting to and from integers

You cast function pointers directly to integers:

    let fnptr: fn(i32) -> i32 = |x| x+2;
    let fnptr_addr = fnptr as usize;

Run

However, a direct cast back is not possible. You need to use `transmute`:

    let fnptr = fnptr_addr as *const ();
    let fnptr: fn(i32) -> i32 = unsafe { std::mem::transmute(fnptr) };
    assert_eq!(fnptr(40), 42);

Run

Crucially, we `as`-cast to a raw pointer before `transmute`ing to a function pointer. This avoids an integer-to-pointer `transmute`, which can be problematic. Transmuting between raw pointers and function pointers (i.e., two pointer types) is fine.

Note that all of this is not portable to platforms where function pointers and data pointers have different sizes.

#### Trait implementations

In this documentation the shorthand `fn (T₁, T₂, …, Tₙ)` is used to represent non-variadic function pointers of varying length. Note that this is a convenience notation to avoid repetitive documentation, not valid Rust syntax.

Due to a temporary restriction in Rust’s type system, these traits are only implemented on functions that take 12 arguments or less, with the `"Rust"` and `"C"` ABIs. In the future, this may change:

- `PartialEq`
- `Eq`
- `PartialOrd`
- `Ord`
- `Hash`
- `Pointer`
- `Debug`

The following traits are implemented for function pointers with any number of arguments and any ABI. These traits have implementations that are automatically generated by the compiler, so are not limited by missing language features:

- `Clone`
- `Copy`
- `Send`
- `Sync`
- `Unpin`
- `UnwindSafe`
- `RefUnwindSafe`

In addition, all safe function pointers implement `Fn`, `FnMut`, and `FnOnce`, because these traits are specially known to the compiler.

## Trait Implementations§

source§

### impl<Ret, T> Clone for fn (T₁, T₂, …, Tₙ) -> Ret

This trait is implemented on function pointers with any number of arguments.

source§

#### fn clone(&self) -> Self

Returns a copy of the value. Read more
source§

#### fn clone_from(&mut self, source: &Self)

Performs copy-assignment from `source`. Read more
source§

### impl<Ret, T> Copy for fn (T₁, T₂, …, Tₙ) -> Ret

This trait is implemented on function pointers with any number of arguments.

## Auto Trait Implementations§

§

### impl<Ret, T> RefUnwindSafe for fn (T₁, T₂, …, Tₙ) -> Ret

§

### impl<Ret, T> Send for fn (T₁, T₂, …, Tₙ) -> Ret

§

### impl<Ret, T> Sync for fn (T₁, T₂, …, Tₙ) -> Ret

§

### impl<Ret, T> Unpin for fn (T₁, T₂, …, Tₙ) -> Ret

§

### impl<Ret, T> UnwindSafe for fn (T₁, T₂, …, Tₙ) -> Ret

## Blanket Implementations§

source§

### impl<T> Any for Twhere T: 'static + ?Sized,

source§

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more
source§

### impl<T> Borrow<T> for Twhere T: ?Sized,

source§

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

### impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

### impl<F> Debug for Fwhere F: FnPtr,

source§

#### fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more
source§

### impl<T> From<T> for T

source§

#### fn from(t: T) -> T

Returns the argument unchanged.

source§

### impl<F> Hash for Fwhere F: FnPtr,

source§

#### fn hash<HH>(&self, state: &mut HH)where HH: Hasher,

Feeds this value into the given `Hasher`. Read more
1.3.0 · source§

#### fn hash_slice<H>(data: &[Self], state: &mut H)where H: Hasher, Self: Sized,

Feeds a slice of this type into the given `Hasher`. Read more
source§

### impl<T, U> Into<U> for Twhere U: From<T>,

source§

#### fn into(self) -> U

Calls `U::from(self)`.

That is, this conversion is whatever the implementation of `From<T> for U` chooses to do.

source§

### impl<F> Ord for Fwhere F: FnPtr,

source§

#### fn cmp(&self, other: &F) -> Ordering

This method returns an `Ordering` between `self` and `other`. Read more
1.21.0 · source§

#### fn max(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the maximum of two values. Read more
1.21.0 · source§

#### fn min(self, other: Self) -> Selfwhere Self: Sized,

Compares and returns the minimum of two values. Read more
1.50.0 · source§

#### fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd,

Restrict a value to a certain interval. Read more
source§

### impl<F> PartialEq for Fwhere F: FnPtr,

source§

#### fn eq(&self, other: &F) -> bool

This method tests for `self` and `other` values to be equal, and is used by `==`.
source§

#### fn ne(&self, other: &Rhs) -> bool

This method tests for `!=`. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

### impl<F> PartialOrd for Fwhere F: FnPtr,

source§

#### fn partial_cmp(&self, other: &F) -> Option<Ordering>

This method returns an ordering between `self` and `other` values if one exists. Read more
source§

#### fn lt(&self, other: &Rhs) -> bool

This method tests less than (for `self` and `other`) and is used by the `<` operator. Read more
source§

#### fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for `self` and `other`) and is used by the `<=` operator. Read more
source§

#### fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for `self` and `other`) and is used by the `>` operator. Read more
source§

#### fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for `self` and `other`) and is used by the `>=` operator. Read more
source§

### impl<'a, F> Pattern<'a> for Fwhere F: FnMut(char) -> bool,

§

#### type Searcher = CharPredicateSearcher<'a, F>

🔬This is a nightly-only experimental API. (`pattern` #27721)
Associated searcher for this pattern
source§

#### fn into_searcher(self, haystack: &'a str) -> CharPredicateSearcher<'a, F>

🔬This is a nightly-only experimental API. (`pattern` #27721)
Constructs the associated searcher from `self` and the `haystack` to search in.
source§

#### fn is_contained_in(self, haystack: &'a str) -> bool

🔬This is a nightly-only experimental API. (`pattern` #27721)
Checks whether the pattern matches anywhere in the haystack
source§

#### fn is_prefix_of(self, haystack: &'a str) -> bool

🔬This is a nightly-only experimental API. (`pattern` #27721)
Checks whether the pattern matches at the front of the haystack
source§

#### fn strip_prefix_of(self, haystack: &'a str) -> Option<&'a str>

🔬This is a nightly-only experimental API. (`pattern` #27721)
Removes the pattern from the front of haystack, if it matches.
source§

#### fn is_suffix_of(self, haystack: &'a str) -> bool where CharPredicateSearcher<'a, F>: ReverseSearcher<'a>,

🔬This is a nightly-only experimental API. (`pattern` #27721)
Checks whether the pattern matches at the back of the haystack
source§

#### fn strip_suffix_of(self, haystack: &'a str) -> Option<&'a str>where CharPredicateSearcher<'a, F>: ReverseSearcher<'a>,

🔬This is a nightly-only experimental API. (`pattern` #27721)
Removes the pattern from the back of haystack, if it matches.
source§

### impl<F> Pointer for Fwhere F: FnPtr,

source§

#### fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.
source§

### impl<T> ToOwned for Twhere T: Clone,

§

#### type Owned = T

The resulting type after obtaining ownership.
source§

#### fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

#### fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

### impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

#### type Error = Infallible

The type returned in the event of a conversion error.
source§

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

### impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

#### fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

### impl<F> Eq for Fwhere F: FnPtr,