nz

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.

Features

No unsafe code
No dependencies
no_std compatible
Supports all core::num::NonZero{Integer} types
Compile-time evaluation and zero detection

`NonZero` 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! |

Basic usage

``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 });

asserteq!(1, NZMIN.get());

asserteq!(2, nztwo.get());

assert_eq!(6, six.get());

assert_eq!(5, five.get());

assert_eq!(9, RES.get());

assert_eq!(8, res.get());

```

Limitations

const fn

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)); ```

const hygiene

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.

License

This library is distributed under the terms of either of the following licenses at your option:

nz