1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

//! The never type.
//!
//! This crate defines [`Never`], which is a type that can never be constructed
//! (in type theory parlance, it is "uninhabited"). It is a stable version of
//! the currently-unstable [`!`] type from the standard library.
//!
//! By default, this crate links against `std`. This is enabled via the `std`
//! feature, which is on by default. To make this crate `no_std`, disable
//! default features.
//!
//! [`!`]: https://doc.rust-lang.org/std/primitive.never.html

#![cfg_attr(not(feature = "std"), no_std)]

#[cfg(feature = "std")]
extern crate core;

use core::fmt::{self, Display, Formatter};
#[cfg(feature = "std")]
use std::{
    error::Error,
    io::{BufRead, Read, Seek, SeekFrom, Write},
};

/// A type that can never be constructed.
///
/// `Never` can never be constructed (in type theory parlance, it is
/// "uninhabited"). It represents any computation which never resolves to a
/// particular value (because it runs forever, panics, aborts the process, etc).
/// Because the `Never` type can never be constructed, the existence of a
/// `Never` proves that a piece of code can never be reached.
///
/// For example, we could write a function like:
///
/// ```rust
/// # use never::Never;
/// fn result_into_ok<T>(res: Result<T, Never>) -> T {
///     match res {
///         Ok(t) => t,
///         // This branch can never be taken, and so the
///         // compiler is happy to treat it as evaluating
///         // to whatever type we wish - in this case, `T`.
///         Err(never) => match never {},
///     }
/// }
/// ```
///
/// Generalizing, it is always valid to convert a `Never` into a value of any
/// other type. We provide the [`into_any`] and [`to_any`] methods for this
/// purpose.
///
/// `Never` is a stable version of the currently-unstable [`!`] type from the
/// standard library.
///
/// [`into_any`]: crate::Never::into_any
/// [`to_any`]: crate::Never::to_any
/// [`!`]: https://doc.rust-lang.org/std/primitive.never.html
#[derive(Copy, Clone, Hash, Eq, PartialEq, Ord, PartialOrd, Debug)]
pub enum Never {}

impl Never {
    /// Convert this `Never` into a value of a different type.
    ///
    /// Since a `Never` can never be constructed, this is valid for any `Sized`
    /// type.
    pub fn into_any<T>(self) -> T {
        match self {}
    }

    /// Convert this `Never` into a value of a different type.
    ///
    /// Since a `Never` can never be constructed, this is valid for any `Sized`
    /// type.
    pub fn to_any<T>(&self) -> T {
        match *self {}
    }
}

impl<T: ?Sized> AsRef<T> for Never {
    fn as_ref(&self) -> &T {
        self.to_any()
    }
}

impl<T: ?Sized> AsMut<T> for Never {
    fn as_mut(&mut self) -> &mut T {
        self.to_any()
    }
}

impl Display for Never {
    fn fmt(&self, _: &mut Formatter<'_>) -> fmt::Result {
        self.to_any()
    }
}

#[cfg(feature = "std")]
impl Error for Never {}

#[cfg(feature = "std")]
impl Read for Never {
    fn read(&mut self, _buf: &mut [u8]) -> std::io::Result<usize> {
        self.to_any()
    }
}

#[cfg(feature = "std")]
impl BufRead for Never {
    fn fill_buf(&mut self) -> std::io::Result<&[u8]> {
        self.to_any()
    }

    fn consume(&mut self, _amt: usize) {
        self.to_any()
    }
}

#[cfg(feature = "std")]
impl Seek for Never {
    fn seek(&mut self, _pos: SeekFrom) -> std::io::Result<u64> {
        self.to_any()
    }
}

#[cfg(feature = "std")]
impl Write for Never {
    fn write(&mut self, _buf: &[u8]) -> std::io::Result<usize> {
        self.to_any()
    }

    fn flush(&mut self) -> std::io::Result<()> {
        self.to_any()
    }
}