never - Rust
Description: API documentation for the Rust `never` primitive in crate `std`.
Keywords: rust, rustlang, rust-lang, never

# [−]Primitive Type never

🔬 This is a nightly-only experimental API. (`never_type` #35121)

The `!` type, also called "never".

`!` represents the type of computations which never resolve to any value at all. For example, the `exit` function `fn exit(code: i32) -> !` exits the process without ever returning, and so returns `!`.

`break`, `continue` and `return` expressions also have type `!`. For example we are allowed to write:

    #![feature(never_type)]
    let x: ! = {
        return 123
    };

Run

Although the `let` is pointless here, it illustrates the meaning of `!`. Since `x` is never assigned a value (because `return` returns from the entire function), `x` can be given type `!`. We could also replace `return 123` with a `panic!` or a never-ending `loop` and this code would still be valid.

A more realistic usage of `!` is in this code:

    let num: u32 = match get_a_number() {
        Some(num) => num,
        None => break,
    };

Run

Both match arms must produce values of type `u32`, but since `break` never produces a value at all we know it can never produce a value which isn't a `u32`. This illustrates another behaviour of the `!` type - expressions with type `!` will coerce into any other type.

# `!` and generics

## Infallible errors

The main place you'll see `!` used explicitly is in generic code. Consider the `FromStr` trait:

    trait FromStr: Sized {
        type Err;
        fn from_str(s: &str) -> Result<Self, Self::Err>;
    }

Run

When implementing this trait for `String` we need to pick a type for `Err`. And since converting a string into a string will never result in an error, the appropriate type is `!`. (Currently the type actually used is an enum with no variants, though this is only because `!` was added to Rust at a later date and it may change in the future.) With an `Err` type of `!`, if we have to call `String::from_str` for some reason the result will be a `Result<String, !>` which we can unpack like this:

ⓘThis example is not tested

    #[feature(exhaustive_patterns)]
    // NOTE: this does not work today!
    let Ok(s) = String::from_str("hello");

Run

Since the `Err` variant contains a `!`, it can never occur. If the `exhaustive_patterns` feature is present this means we can exhaustively match on `Result<T, !>` by just taking the `Ok` variant. This illustrates another behaviour of `!` - it can be used to "delete" certain enum variants from generic types like `Result`.

## Infinite loops

While `Result<T, !>` is very useful for removing errors, `!` can also be used to remove successes as well. If we think of `Result<T, !>` as "if this function returns, it has not errored," we get a very intuitive idea of `Result<!, E>` as well: if the function returns, it has errored.

For example, consider the case of a simple web server, which can be simplified to:

ⓘThis example is not tested

    loop {
        let (client, request) = get_request().expect("disconnected");
        let response = request.process();
        response.send(client);
    }

Run

Currently, this isn't ideal, because we simply panic whenever we fail to get a new connection. Instead, we'd like to keep track of this error, like this:

ⓘThis example is not tested

    loop {
        match get_request() {
            Err(err) => break err,
            Ok((client, request)) => {
                let response = request.process();
                response.send(client);
            },
        }
    }

Run

Now, when the server disconnects, we exit the loop with an error instead of panicking. While it might be intuitive to simply return the error, we might want to wrap it in a `Result<!, E>` instead:

ⓘThis example is not tested

    fn server_loop() -> Result<!, ConnectionError> {
        loop {
            let (client, request) = get_request()?;
            let response = request.process();
            response.send(client);
        }
    }

Run

Now, we can use `?` instead of `match`, and the return type makes a lot more sense: if the loop ever stops, it means that an error occurred. We don't even have to wrap the loop in an `Ok` because `!` coerces to `Result<!, ConnectionError>` automatically.

# `!` and traits

When writing your own traits, `!` should have an `impl` whenever there is an obvious `impl` which doesn't `panic!`. The reason is that functions returning an `impl Trait` where `!` does not have an `impl` of `Trait` cannot diverge as their only possible code path. In other words, they can't return `!` from every code path. As an example, this code doesn't compile:

ⓘThis example deliberately fails to compile

    use core::ops::Add;

    fn foo() -> impl Add<u32> {
        unimplemented!()
    }

Run

But this code does:

    use core::ops::Add;

    fn foo() -> impl Add<u32> {
        if true {
            unimplemented!()
        } else {
            0
        }
    }

Run

The reason is that, in the first example, there are many possible types that `!` could coerce to, because many types implement `Add<u32>`. However, in the second example, the `else` branch returns a `0`, which the compiler infers from the return type to be of type `u32`. Since `u32` is a concrete type, `!` can and will be coerced to it. See issue #36375 for more information on this quirk of `!`.

As it turns out, though, most traits can have an `impl` for `!`. Take `Debug` for example:

    #![feature(never_type)]
    impl Debug for ! {
        fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
            *self
        }
    }

Run

Once again we're using `!`'s ability to coerce into any other type, in this case `fmt::Result`. Since this method takes a `&!` as an argument we know that it can never be called (because there is no value of type `!` for it to be called with). Writing `*self` essentially tells the compiler "We know that this code can never be run, so just treat the entire function body as having type `fmt::Result`". This pattern can be used a lot when implementing traits for `!`. Generally, any trait which only has methods which take a `self` parameter should have such an impl.

On the other hand, one trait which would not be appropriate to implement is `Default`:

    trait Default {
        fn default() -> Self;
    }

Run

Since `!` has no values, it has no default value either. It's true that we could write an `impl` for this which simply panics, but the same is true for any type (we could `impl Default` for (eg.) `File` by just making `default()` panic.)

## Trait Implementations

### `impl Clone for !`[src]

#### `pub fn clone(&self) -> !`[src]

Returns a copy of the value. Read more

#### `fn clone_from(&mut self, source: &Self)`1.0.0[src]

Performs copy-assignment from `source`. Read more

### `impl Copy for !`[src]

### `impl Debug for !`[src]

#### `pub fn fmt(&self, &mut Formatter<'_>) -> Result<(), Error>`[src]

Formats the value using the given formatter. Read more

### `impl Display for !`[src]

#### `pub fn fmt(&self, &mut Formatter<'_>) -> Result<(), Error>`[src]

Formats the value using the given formatter. Read more

### `impl Eq for !`[src]

### `impl Error for !`[src]

#### `fn source(&self) -> Option<&(dyn Error + 'static)>`1.30.0[src]

The lower-level source of this error, if any. Read more

#### `fn backtrace(&self) -> Option<&Backtrace>`[src]

🔬 This is a nightly-only experimental API. (`backtrace` #53487)

Returns a stack backtrace, if available, of where this error occurred. Read more

#### `fn description(&self) -> &str`1.0.0[src]

👎 Deprecated since 1.42.0:

use the Display impl or to_string()

Read more

#### `fn cause(&self) -> Option<&dyn Error>`1.0.0[src]

👎 Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

### `impl Hash for !`1.29.0[src]

#### `pub fn hash<H>(&self, &mut H) where
H: Hasher,` [src]

Feeds this value into the given `Hasher`. Read more

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

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

### `impl Ord for !`[src]

#### `pub fn cmp(&self, &!) -> Ordering`[src]

This method returns an `Ordering` between `self` and `other`. Read more

#### `#[must_use]fn max(self, other: Self) -> Self`1.21.0[src]

Compares and returns the maximum of two values. Read more

#### `#[must_use]fn min(self, other: Self) -> Self`1.21.0[src]

Compares and returns the minimum of two values. Read more

#### `#[must_use]fn clamp(self, min: Self, max: Self) -> Self`[src]

🔬 This is a nightly-only experimental API. (`clamp` #44095)

Restrict a value to a certain interval. Read more

### `impl PartialEq<!> for !`[src]

#### `pub fn eq(&self, &!) -> bool`[src]

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

#### `#[must_use]fn ne(&self, other: &Rhs) -> bool`1.0.0[src]

This method tests for `!=`.

### `impl PartialOrd<!> for !`[src]

#### `pub fn partial_cmp(&self, &!) -> Option<Ordering>`[src]

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

#### `#[must_use]fn lt(&self, other: &Rhs) -> bool`1.0.0[src]

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

#### `#[must_use]fn le(&self, other: &Rhs) -> bool`1.0.0[src]

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

#### `#[must_use]fn gt(&self, other: &Rhs) -> bool`1.0.0[src]

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

#### `#[must_use]fn ge(&self, other: &Rhs) -> bool`1.0.0[src]

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

### `impl Termination for !`[src]

#### `fn report(self) -> i32`[src]

🔬 This is a nightly-only experimental API. (`termination_trait_lib` #43301)

Is called to get the representation of the value as status code. This status code is returned to the operating system. Read more