never/
lib.rs

1// Copyright 2019 The Fuchsia Authors. All rights reserved.
2// Use of this source code is governed by a BSD-style license that can be
3// found in the LICENSE file.
4
5//! The never type.
6//!
7//! This crate defines [`Never`], which is a type that can never be constructed
8//! (in type theory parlance, it is "uninhabited"). It is a stable version of
9//! the currently-unstable [`!`] type from the standard library.
10//!
11//! By default, this crate links against `std`. This is enabled via the `std`
12//! feature, which is on by default. To make this crate `no_std`, disable
13//! default features.
14//!
15//! [`!`]: https://doc.rust-lang.org/std/primitive.never.html
16
17#![cfg_attr(not(feature = "std"), no_std)]
18
19#[cfg(feature = "std")]
20extern crate core;
21
22use core::fmt::{self, Display, Formatter};
23#[cfg(feature = "std")]
24use std::{
25    error::Error,
26    io::{BufRead, Read, Seek, SeekFrom, Write},
27};
28
29/// A type that can never be constructed.
30///
31/// `Never` can never be constructed (in type theory parlance, it is
32/// "uninhabited"). It represents any computation which never resolves to a
33/// particular value (because it runs forever, panics, aborts the process, etc).
34/// Because the `Never` type can never be constructed, the existence of a
35/// `Never` proves that a piece of code can never be reached.
36///
37/// For example, we could write a function like:
38///
39/// ```rust
40/// # use never::Never;
41/// fn result_into_ok<T>(res: Result<T, Never>) -> T {
42///     match res {
43///         Ok(t) => t,
44///         // This branch can never be taken, and so the
45///         // compiler is happy to treat it as evaluating
46///         // to whatever type we wish - in this case, `T`.
47///         Err(never) => match never {},
48///     }
49/// }
50/// ```
51///
52/// Generalizing, it is always valid to convert a `Never` into a value of any
53/// other type. We provide the [`into_any`] and [`to_any`] methods for this
54/// purpose.
55///
56/// `Never` is a stable version of the currently-unstable [`!`] type from the
57/// standard library.
58///
59/// [`into_any`]: crate::Never::into_any
60/// [`to_any`]: crate::Never::to_any
61/// [`!`]: https://doc.rust-lang.org/std/primitive.never.html
62#[derive(Copy, Clone, Hash, Eq, PartialEq, Ord, PartialOrd, Debug)]
63pub enum Never {}
64
65impl Never {
66    /// Convert this `Never` into a value of a different type.
67    ///
68    /// Since a `Never` can never be constructed, this is valid for any `Sized`
69    /// type.
70    pub fn into_any<T>(self) -> T {
71        match self {}
72    }
73
74    /// Convert this `Never` into a value of a different type.
75    ///
76    /// Since a `Never` can never be constructed, this is valid for any `Sized`
77    /// type.
78    pub fn to_any<T>(&self) -> T {
79        match *self {}
80    }
81}
82
83impl<T: ?Sized> AsRef<T> for Never {
84    fn as_ref(&self) -> &T {
85        self.to_any()
86    }
87}
88
89impl<T: ?Sized> AsMut<T> for Never {
90    fn as_mut(&mut self) -> &mut T {
91        self.to_any()
92    }
93}
94
95impl Display for Never {
96    fn fmt(&self, _: &mut Formatter<'_>) -> fmt::Result {
97        self.to_any()
98    }
99}
100
101#[cfg(feature = "std")]
102impl Error for Never {}
103
104#[cfg(feature = "std")]
105impl Read for Never {
106    fn read(&mut self, _buf: &mut [u8]) -> std::io::Result<usize> {
107        self.to_any()
108    }
109}
110
111#[cfg(feature = "std")]
112impl BufRead for Never {
113    fn fill_buf(&mut self) -> std::io::Result<&[u8]> {
114        self.to_any()
115    }
116
117    fn consume(&mut self, _amt: usize) {
118        self.to_any()
119    }
120}
121
122#[cfg(feature = "std")]
123impl Seek for Never {
124    fn seek(&mut self, _pos: SeekFrom) -> std::io::Result<u64> {
125        self.to_any()
126    }
127}
128
129#[cfg(feature = "std")]
130impl Write for Never {
131    fn write(&mut self, _buf: &[u8]) -> std::io::Result<usize> {
132        self.to_any()
133    }
134
135    fn flush(&mut self) -> std::io::Result<()> {
136        self.to_any()
137    }
138}
never/lib.rs

never/
lib.rs
