Skip to content

README.md

Latest commit

 

History

History
99 lines (84 loc) · 5.41 KB

README.md

File metadata and controls

99 lines (84 loc) · 5.41 KB
Raw

This crate provides two types of bounded integer.

Macro-generated bounded integers

The bounded_integer! macro allows you to define your own bounded integer type, given a specific (inclusive) range it inhabits. For example:

bounded_integer! {
    struct MyInteger(0, 7);
}
let num = MyInteger::new(5).unwrap();
assert_eq!(num, 5);

This macro supports both structs and enums. See the examples module for the documentation of generated types.

Const generics-based bounded integers

You can also create ad-hoc bounded integers via types in this library that use const generics, for example:

let num = <BoundedU8<0, 7>>::new(5).unwrap();
assert_eq!(num, 5);

These integers are shorter to use as they don't require a type declaration or explicit name. However due to the limits of const generics, they may not implement some traits – namely [Default], bytemuck’s Zeroable and zerocopy’s FromZeros. Also, unlike their macro counterparts they will not be subject to niche layout optimizations.

no_std

All the integers in this crate depend only on libcore and so work in #![no_std] environments.

Crate Features

By default, no crate features are enabled.

  • std: Interopate with std — implies alloc. Has no effect currently.
  • alloc: Interopate with alloc. Has no effect currently.
  • macro: Enable the bounded_integer! macro.
  • arbitrary1: Implement Arbitrary for the bounded integers. This is useful when using bounded integers as fuzzing inputs.
  • bytemuck1: Implement Contiguous and NoUninit for all bounded integers, and Zeroable for macro-generated bounded integers that support it.
  • num-traits02: Implement Bounded, AsPrimitive, FromPrimitive, NumCast, ToPrimitive, CheckedAdd, CheckedDiv, CheckedMul, CheckedNeg, CheckedRem, CheckedSub, MulAdd, SaturatingAdd, SaturatingMul and SaturatingSub for all bounded integers.
  • serde1: Implement Serialize and Deserialize for the bounded integers, making sure all values will never be out of bounds.
  • schemars1: Implement JsonSchema for the bounded integers, describing them as their underlying primitive constrained to the type’s range via minimum and maximum. Bounds of i128/u128-backed integers that fall outside the i64/u64 range are omitted unless serde_json’s arbitrary_precision feature is enabled (which has a significant runtime cost).
  • zerocopy: Implement IntoBytes and Immutable for all bounded integers, Unaligned for ones backed by u8 or i8, and FromZeros for suitable macro-generated ones.
  • step_trait: Implement the Step trait which allows the bounded integers to be easily used in ranges. This will require you to use nightly and place #![feature(step_trait)] in your crate root if you use the macro.