The nz crate provides a collection of macros that simplify the creation of
new instances of non-zero numeric types implemented in core::num. With these macros, you can easily generate constants of such numeric types using
literals, constant values or expressions, all at compile time.
no_std compatiblecore::num::NonZero{Integer} types| 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;
// A NonZero 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);
let five = nz::u8!({ const FIVE: u8 = 5; FIVE });
// or even a constant expression
const RES: NonZeroU8 = nz::u8!({ 3 + 7 } - NZ_MIN.get());
// non-constant expression leads to compile-time error
// const OUTPUT: NonZeroU8 = nz::u8!({ 3 + 7 } - nz_two.get()); // casued by `mz_two.get()`
let result_as_nz = nz::u8!((NZ_MIN.get() & NZ_MAX.get()) + 7);
Declarative macros (such as all the nz macros) cannot be used with
constant function arguments since they are not currently recognized
as 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
// the line below causes compile error
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 reference 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 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 the macro
// it won't collide when passing it in a constant
// expression, because it is not in the most outer
// scope where a constant is declared
const OK: NonZeroU16 = nz::u16!(CHECKZERO.get());
// using NUM.get() is fine
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
const FAILS: NonZeroU16 = nz::u16!(
_NZINTERNALNUM1_ // <-- error
);
```
This "collision" between the outer and inner constants leads to a compile-time
error, specifically error [E0391],
because the inner macro constant tries to use itself, creating a cyclic dependency
during the evaluation of the macro at compile-time. Essentially, the code above has
the same error as this single line:
rust, compile_fail
const X: u8 = X;
This library is distributed under the terms of either of the following licenses at your option: