non_zero_size/
lib.rs

1//! Non-zero sizes.
2//!
3//! This crate provides the [`Size`] type representing non-zero sizes, along with
4//! [`size!`] and [`const_size!`] macros used for constructing values of said type.
5
6#![forbid(unsafe_code)]
7#![deny(missing_docs)]
8#![no_std]
9
10use core::num::NonZero;
11
12/// The error message used for when the provided size is zero.
13pub const NON_ZERO: &str = "expected non-zero size";
14
15/// Represents non-zero sizes, [`NonZero<usize>`].
16pub type Size = NonZero<usize>;
17
18/// Constructs [`Size`], panicking if the provided size is zero.
19///
20/// # Examples
21///
22/// ```
23/// use non_zero_size::size;
24///
25/// let nekit = 13;
26///
27/// let non_zero = size!(nekit);
28///
29/// assert_eq!(non_zero.get(), nekit);
30/// ```
31///
32/// Panicking on zero:
33///
34/// ```should_panic
35/// use non_zero_size::size;
36///
37/// let never = size!(0);
38/// ```
39///
40/// Failing compilation on zero in `const` contexts (see also [`const_size`]):
41///
42/// ```compile_fail
43/// use non_zero_size::size;
44///
45/// let never = const { size!(0) };
46/// ```
47#[macro_export]
48macro_rules! size {
49    ($value: expr) => {
50        $crate::Size::new($value).expect($crate::NON_ZERO)
51    };
52}
53
54/// Constantly constructs [`Size`], failing compilation if the provided size is zero.
55///
56/// Note that the provided expression must be const-evaluatable, else the compilation will fail.
57///
58/// # Examples
59///
60/// ```
61/// use non_zero_size::const_size;
62///
63/// const NICE: usize = 69;
64///
65/// let non_zero = const_size!(NICE);
66///
67/// assert_eq!(non_zero.get(), NICE);
68/// ```
69///
70/// Failing compilation on zero:
71///
72/// ```compile_fail
73/// use non_zero_size::const_size;
74///
75/// let never = const_size!(0);
76/// ```
77#[macro_export]
78macro_rules! const_size {
79    ($value: expr) => {
80        const { $crate::size!($value) }
81    };
82}
non_zero_size/lib.rs

non_zero_size/
lib.rs
