never-0.1.0/Cargo.toml0000644000000017251363525330600102600ustar00# THIS FILE IS AUTOMATICALLY GENERATED BY CARGO # # When uploading crates to the registry Cargo will automatically # "normalize" Cargo.toml files for maximal compatibility # with all versions of Cargo and also rewrite `path` dependencies # to registry (e.g., crates.io) dependencies # # If you believe there's an error in this file please file an # issue against the rust-lang/cargo repository. If you're # editing this file be aware that the upstream Cargo.toml # will likely look very different (and much more reasonable) [package] edition = "2018" name = "never" version = "0.1.0" authors = ["Joshua Liebow-Feeser "] include = ["src/*", "Cargo.toml"] description = "A stable version of the unstable never type (!)" keywords = ["never", "void", "unstable", "stable"] categories = ["no-std", "rust-patterns"] license = "BSD-3-Clause" repository = "https://fuchsia.googlesource.com/fuchsia/+/master/garnet/lib/rust/never" [features] default = ["std"] std = [] never-0.1.0/Cargo.toml.orig010064411536020257523000000012341363525317100137650ustar0000000000000000# Copyright 2020 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. # This file is used when publishing to crates.io [package] name = "never" version = "0.1.0" authors = ["Joshua Liebow-Feeser "] edition = "2018" description = "A stable version of the unstable never type (!)" repository = "https://fuchsia.googlesource.com/fuchsia/+/master/garnet/lib/rust/never" license = "BSD-3-Clause" keywords = ["never", "void", "unstable", "stable"] categories = ["no-std", "rust-patterns"] include = ["src/*", "Cargo.toml"] [features] std = [] default = ["std"] never-0.1.0/src/lib.rs010064411536020257523000000073231363525263100130060ustar0000000000000000// 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(res: Result) -> 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(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(&self) -> T { match *self {} } } impl AsRef for Never { fn as_ref(&self) -> &T { self.to_any() } } impl AsMut 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 { 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 { self.to_any() } } #[cfg(feature = "std")] impl Write for Never { fn write(&mut self, _buf: &[u8]) -> std::io::Result { self.to_any() } fn flush(&mut self) -> std::io::Result<()> { self.to_any() } }