nonzero_ext/
lib.rs

1//! # Traits to represent generic nonzero integer types
2//! [![Build Status](https://travis-ci.com/antifuchs/nonzero_ext.svg?branch=master)](https://travis-ci.com/antifuchs/nonzero_ext) [![Docs](https://docs.rs/nonzero_ext/badge.svg)](https://docs.rs/nonzero_ext)
3//!
4//! Rust ships with non-zero integer types now, which let programmers
5//! promise (memory-savingly!) that a number can never be zero. That's
6//! great, but sadly the standard library has not got a whole lot of
7//! tools to help you use them ergonomically.
8//!
9//! ## A macro for non-zero constant literals
10//!
11//! Creating and handling constant literals is neat, but the standard
12//! library (and the rust parser at the moment) have no affordances to
13//! easily create values of `num::NonZeroU*` types from constant
14//! literals. This crate ships a `nonzero!` macro that lets you write
15//! `nonzero!(20u32)`, which checks at compile time that the constant
16//! being converted is non-zero, instead of the cumbersome (and
17//! runtime-checked!)  `NonZeroU32::new(20).unwrap()`.
18//!
19//! ## Traits for generic non-zeroness
20//!
21//! The stdlib `num::NonZeroU*` types do not implement any common
22//! traits (and neither do their zeroable equivalents).  Where this
23//! lack of traits in the standard library becomes problematic is if
24//! you want to write a function that takes a vector of integers, and
25//! that returns a vector of the corresponding non-zero integer types,
26//! minus any elements that were zero in the original. You can write
27//! that with the standard library quite easily for concrete types:
28//!
29//! ```rust
30//! # use std::num::NonZeroU8;
31//! fn only_nonzeros(v: Vec<u8>) -> Vec<NonZeroU8>
32//! {
33//!     v.into_iter()
34//!         .filter_map(|n| NonZeroU8::new(n))
35//!         .collect::<Vec<NonZeroU8>>()
36//! }
37//! # #[macro_use] extern crate nonzero_ext;
38//! # fn main() {
39//! let expected: Vec<NonZeroU8> = vec![nonzero!(20u8), nonzero!(5u8)];
40//! assert_eq!(expected, only_nonzeros(vec![0, 20, 5]));
41//! # }
42//! ```
43//!
44//! But what if you want to allow this function to work with any
45//! integer type that has a corresponding non-zero type? This crate
46//! can help:
47//!
48//! ```rust
49//! # use std::num::{NonZeroU8, NonZeroU32};
50//! # use nonzero_ext::{NonZeroAble};
51//! fn only_nonzeros<I>(v: Vec<I>) -> Vec<I::NonZero>
52//! where
53//!     I: Sized + NonZeroAble,
54//! {
55//!     v.into_iter()
56//!         .filter_map(|n| n.as_nonzero())
57//!         .collect::<Vec<I::NonZero>>()
58//! }
59//!
60//! # #[macro_use] extern crate nonzero_ext;
61//! # fn main() {
62//! // It works for `u8`:
63//! let input_u8: Vec<u8> = vec![0, 20, 5];
64//! let expected_u8: Vec<NonZeroU8> = vec![nonzero!(20u8), nonzero!(5u8)];
65//! assert_eq!(expected_u8, only_nonzeros(input_u8));
66//!
67//! // And it works for `u32`:
68//! let input_u32: Vec<u32> = vec![0, 20, 5];
69//! let expected_u32: Vec<NonZeroU32> = vec![nonzero!(20u32), nonzero!(5u32)];
70//! assert_eq!(expected_u32, only_nonzeros(input_u32));
71//! # }
72//! ```
73//!
74
75#![cfg_attr(not(feature = "std"), no_std)]
76
77mod lib {
78    mod core {
79        #[cfg(feature = "std")]
80        pub use std::*;
81
82        #[cfg(not(feature = "std"))]
83        pub use core::*;
84    }
85    pub use self::core::num::{
86        NonZeroU128, NonZeroU16, NonZeroU32, NonZeroU64, NonZeroU8, NonZeroUsize,
87    };
88}
89
90use self::lib::*;
91
92macro_rules! impl_nonzeroness {
93    ($trait_name:ident, $nonzero_type:ty, $wrapped:ty) => {
94        impl $trait_name for $nonzero_type {
95            type Primitive = $wrapped;
96
97            #[inline]
98            #[cfg_attr(feature = "cargo-clippy", allow(clippy::new_ret_no_self))]
99            fn new(n: $wrapped) -> Option<Self> {
100                Self::new(n)
101            }
102
103            #[inline]
104            fn get(self) -> Self::Primitive {
105                <$nonzero_type>::get(self)
106            }
107        }
108    };
109}
110
111/// A trait identifying a non-zero integral type. It is useful mostly
112/// in order to give to genericized helper functions as `impl NonZero`
113/// arguments.
114pub trait NonZero {
115    /// The primitive type (e.g. `u8`) underlying this integral type.
116    type Primitive;
117
118    /// Creates a new non-zero object from an integer that might be
119    /// zero.
120    fn new(n: Self::Primitive) -> Option<Self>
121    where
122        Self: Sized;
123
124    /// Returns the value as a primitive type.
125    fn get(self) -> Self::Primitive;
126}
127
128impl_nonzeroness!(NonZero, NonZeroU8, u8);
129impl_nonzeroness!(NonZero, NonZeroU16, u16);
130impl_nonzeroness!(NonZero, NonZeroU32, u32);
131impl_nonzeroness!(NonZero, NonZeroU64, u64);
132impl_nonzeroness!(NonZero, NonZeroU128, u128);
133impl_nonzeroness!(NonZero, NonZeroUsize, usize);
134
135/// A trait identifying integral types that have a non-zeroable
136/// equivalent.
137pub trait NonZeroAble {
138    /// The concrete non-zero type represented by an implementation of
139    /// this trait. For example, for `u8`'s implementation, it is
140    /// `NonZeroU8`.
141    type NonZero: NonZero;
142
143    /// Converts the integer to its non-zero equivalent.
144    ///
145    /// # Examples
146    ///
147    /// ### Trying to convert zero
148    /// ``` rust
149    /// # use nonzero_ext::NonZeroAble;
150    /// let n: u16 = 0;
151    /// assert_eq!(n.as_nonzero(), None);
152    /// ```
153    ///
154    /// ### Converting a non-zero value
155    /// ``` rust
156    /// # use nonzero_ext::NonZeroAble;
157    /// # use std::num::NonZeroUsize;
158    /// let n: usize = 20;
159    /// let non0n: NonZeroUsize = n.as_nonzero().expect("should result in a converted value");
160    /// assert_eq!(non0n.get(), 20);
161    /// ```
162    fn as_nonzero(self) -> Option<Self::NonZero>;
163
164    /// Converts the integer to its non-zero equivalent without
165    /// checking for zeroness.
166    ///
167    /// This corresponds to the `new_unchecked` function on the
168    /// corresponding NonZero type.
169    unsafe fn as_nonzero_unchecked(self) -> Self::NonZero;
170}
171
172macro_rules! impl_nonzeroable {
173    ($trait_name:ident, $nonzero_type: ty, $nonzeroable_type:ty) => {
174        impl $trait_name for $nonzeroable_type {
175            type NonZero = $nonzero_type;
176
177            fn as_nonzero(self) -> Option<$nonzero_type> {
178                Self::NonZero::new(self)
179            }
180
181            unsafe fn as_nonzero_unchecked(self) -> $nonzero_type {
182                Self::NonZero::new_unchecked(self)
183            }
184        }
185    };
186}
187
188impl_nonzeroable!(NonZeroAble, NonZeroU8, u8);
189impl_nonzeroable!(NonZeroAble, NonZeroU16, u16);
190impl_nonzeroable!(NonZeroAble, NonZeroU32, u32);
191impl_nonzeroable!(NonZeroAble, NonZeroU64, u64);
192impl_nonzeroable!(NonZeroAble, NonZeroU128, u128);
193impl_nonzeroable!(NonZeroAble, NonZeroUsize, usize);
194
195/// Create non-zero values from constant literals easily.
196///
197/// This macro issues a compile-time check and, if it passes, creates
198/// the corresponding non-zero numeric value from the given
199/// constant. Since the type of constant literals needs to be exactly
200/// known, `nonzero!` requires that you annotate the constant with the
201/// type, so instead of `nonzero!(20)` you must write `nonzero!(20 as
202/// u16)`.
203/// # Examples
204/// ```
205/// # #[macro_use]
206/// # extern crate nonzero_ext;
207/// # fn main() {
208/// nonzero!(20usize);  // => NonZeroUsize
209/// nonzero!(20u32);    // => NonZeroU32
210/// nonzero!(20 as u8); // => NonZeroU8
211/// # }
212/// ```
213///
214/// and passing a zero of any type will fail:
215///
216/// ``` # compile_fail
217/// # #[macro_use]
218/// # extern crate nonzero_ext;
219/// # fn main() {
220/// nonzero!(0u8);
221/// # }
222/// ```
223///
224#[macro_export]
225macro_rules! nonzero {
226    ($n:expr) => {{
227        let helper = || {
228            #[allow(unknown_lints, eq_op)]
229            let _ = [(); ($n as usize) - 1];
230            use $crate::NonZeroAble;
231            unsafe { $n.as_nonzero_unchecked() }
232        };
233        helper()
234    }};
235}
nonzero_ext/lib.rs

nonzero_ext/
lib.rs
