[−]Primitive Type never
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:
#[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:
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:
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:
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!
. As it turns out, 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 PartialOrd<!> for !
[src]
fn partial_cmp(&self, &!) -> Option<Ordering>
[src]
#[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 Hash for !
1.29.0[src]
fn hash<H>(&self, &mut H) where
H: Hasher,
[src]
H: Hasher,
fn hash_slice<H>(data: &[Self], state: &mut H) where
H: Hasher,
1.3.0[src]
H: Hasher,
Feeds a slice of this type into the given [Hasher
]. Read more
impl Eq for !
[src]
impl Clone for !
[src]
fn clone(&self) -> !
[src]
fn clone_from(&mut self, source: &Self)
1.0.0[src]
Performs copy-assignment from source
. Read more
impl Debug for !
[src]
impl Copy for !
[src]
impl Ord for !
[src]
fn cmp(&self, &!) -> Ordering
[src]
fn max(self, other: Self) -> Self
1.21.0[src]
Compares and returns the maximum of two values. Read more
fn min(self, other: Self) -> Self
1.21.0[src]
Compares and returns the minimum of two values. Read more
fn clamp(self, min: Self, max: Self) -> Self
[src]
Restrict a value to a certain interval. Read more
impl PartialEq<!> for !
[src]
fn eq(&self, &!) -> bool
[src]
#[must_use]
fn ne(&self, other: &Rhs) -> bool
1.0.0[src]
This method tests for !=
.
impl Display for !
[src]
impl Error for !
[src]
fn description(&self) -> &str
[src]
fn cause(&self) -> Option<&dyn Error>
1.0.0[src]
replaced by Error::source, which can support downcasting
The lower-level cause of this error, if any. Read more
fn source(&self) -> Option<&(dyn Error + 'static)>
1.30.0[src]
The lower-level source of this error, if any. Read more