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

use core::num::NonZeroU8;
// A `NonZeroU8` type 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 by `nz_two` in this case
// const OUTPUT: NonZeroU8 = nz::u8!({ 3 + 7 } - nz_two.get());
let res = nz::u8!((NZ_MIN.get() & NZ_MAX.get()) + 7);
let five = nz::u8!({ const FIVE: u8 = 5; FIVE });
# assert_eq!(1, NZ_MIN.get());
# assert_eq!(2, nz_two.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.

use core::num::NonZeroU64;

const fn wrapping_add_nz(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.wrapping_add(b.get()))
}
let nz = wrapping_add_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.

use core::num::NonZeroU16;

const NZ: NonZeroU16 = nz::u16!(0xA3FE);
const CHECK_ZERO: 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!(CHECK_ZERO.get());
// using `NZ` is fine for the same reason
const ___NZ___INTERNAL___NUM___1___: 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!(___NZ___INTERNAL___NUM___1___);

More concisely, the problem is:

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 0.2.1

nz