qubit_codec/nz.rs
1// =============================================================================
2// Copyright (c) 2025 - 2026 Haixing Hu.
3//
4// SPDX-License-Identifier: Apache-2.0
5//
6// Licensed under the Apache License, Version 2.0.
7// =============================================================================
8//! Compile-time `NonZeroUsize` construction helpers.
9
10use core::num::NonZeroUsize;
11
12/// Returns a [`NonZeroUsize`] from a known non-zero value.
13///
14/// This helper is const-evaluable, so a zero constant fails during const
15/// evaluation. Constant non-zero inputs compile down without the
16/// `unsafe { NonZeroUsize::new_unchecked(...) }` ceremony otherwise repeated
17/// by concrete codecs.
18///
19/// # Parameters
20///
21/// - `value`: Non-zero item count.
22///
23/// # Returns
24///
25/// Returns a [`NonZeroUsize`] equal to `value`.
26///
27/// # Panics
28///
29/// Panics when `value` is zero.
30#[must_use]
31#[inline(always)]
32pub const fn nz(value: usize) -> NonZeroUsize {
33 match NonZeroUsize::new(value) {
34 Some(value) => value,
35 None => panic!("qubit_codec::nz!(): value must be non-zero"),
36 }
37}
38
39/// Constructs a [`NonZeroUsize`] from a const-evaluable expression.
40///
41/// # Examples
42///
43/// ```
44/// const WIDTH: core::num::NonZeroUsize = qubit_codec::nz!(4);
45///
46/// assert_eq!(WIDTH.get(), 4);
47/// ```
48///
49/// # Panics
50///
51/// Panics when the supplied value is zero.
52#[macro_export]
53macro_rules! nz {
54 ($value:expr) => {{ $crate::nz_const($value) }};
55}
56
57/// Const-friendly function used by [`nz!`](crate::nz).
58///
59/// The macro qualifies this function through `$crate`, allowing callers to
60/// import only the macro.
61///
62/// # Parameters
63///
64/// - `value`: Non-zero item count.
65///
66/// # Returns
67///
68/// Returns a [`NonZeroUsize`] equal to `value`.
69///
70/// # Panics
71///
72/// Panics when `value` is zero.
73#[doc(hidden)]
74#[must_use]
75#[inline(always)]
76pub const fn nz_const(value: usize) -> NonZeroUsize {
77 nz(value)
78}