![github] ![crates.io] ![docs.rs] ![rust-ci] ![msrv] ![unsafety] [![license]](#license)
The nz crate provides a collection of macros that simplify the creation
of non-zero numerics implemented in core::num.
With these macros, you can easily generate constants of all the NonZero
types using literals, constant values or expressions at compile time.
no_std compatiblecore::num::NonZero{Integer} typesNonZero macros| Type | Macro |
|------|-------|
| NonZeroI8 | nz::i8! |
| NonZeroI16 | nz::i16! |
| NonZeroI32 | nz::i32! |
| NonZeroI64 | nz::i64! |
| NonZeroI128 | nz::i128! |
| NonZeroIsize | nz::isize! |
| NonZeroU8 | nz::u8! |
| NonZeroU16 | nz::u16! |
| NonZeroU32 | nz::u32! |
| NonZeroU64 | nz::u64! |
| NonZeroU128 | nz::u128! |
| NonZeroUsize | nz::usize! |
``rust
use core::num::NonZeroU8;
// ANonZeroU8type can be constructed by different types
// of arguments when using the matching macro.
// such argument can be a numeric literal
const NZ_MIN: NonZeroU8 = nz::u8!(1);
let nz_two = nz::u8!(2);
// or a constant value
const NZ_MAX: NonZeroU8 = nz::u8!(u8::MAX);
const SIX: u8 = 6;
let six = nz::u8!(SIX);
// or even a constant expression
const RES: NonZeroU8 = nz::u8!({ 3 + 7 } - NZ_MIN.get());
// non-constant expression results in a compile-time error
// which is caused bynztwo` in this case
// const OUTPUT: NonZeroU8 = nz::u8!({ 3 + 7 } - nztwo.get());
let res = nz::u8!((NZMIN.get() & NZMAX.get()) + 7);
let five = nz::u8!({ const FIVE: u8 = 5; FIVE });
```
Declarative macros, such as all the nz macros, cannot be used with
constant function arguments since they are not considered constant
values, as demonstrated in the code below.
```rust, compile_fail use core::num::NonZeroU64;
const fn wrappingaddnz(a: u64, b: NonZeroU64) -> NonZeroU64 {
// a and b is not constant which results
// in a compile-time error when passed to
// nz::u64! in an expression
nz::u64!(a.wrappingadd(b.get()))
}
let nz = wrappingadd_nz(2, nz::u64!(1));
```
When constants are used in a declarative macro, specifically in the most outer scope where a constant can be declared, there is a possibility of cyclic dependency when an expression is expected as an argument and an outer constant is used within that expression. This collision can occur if any of the inner constants share the same identifier as the outer constant after the macro is expanded at compile-time. The code snippet below demonstrates this scenario.
```rust, compile_fail use core::num::NonZeroU16;
const NZ: NonZeroU16 = nz::u16!(0xA3FE);
const CHECKZERO: NonZeroU16 = nz::u16!(777);
// although CHECK_ZERO is used in nz::u16! macro, it will not result in
// an error when a constant with the same name is passed as part
// of a constant expression, because this inner macro constant is not
// declared in the most outer scope
const OK: NonZeroU16 = nz::u16!(CHECKZERO.get());
// using NZ is fine for the same reason
const NZINTERNALNUM1: u16
= nz::u16!(NZ.get()).get();
// using ___NZ___INTERNAL___NUM___1___ constant as the argument
// causes compile-time error in the code line below, because the
// internal macro constant has the same identifier as the constant
// specified in the macro argument
const _: NonZeroU16 = nz::u16!(NZINTERNALNUM1);
```
More concisely, the problem is:
rust, compile_fail
const X: u8 = X;
This collision between the outer and inner constants results in a compile-time error[^cd_error], because the inner macro constant depends on itself, creating a cyclic dependency.
This library is distributed under the terms of either of the following licenses at your option: