Struct ConstrainedU16 

pub struct ConstrainedU16<const MIN: u16, const MAX: u16, const DEF: u16 = MIN>(/* private fields */);

An u16 value that is constrained within an inclusive range.

The range is defined at compile time, by assigning values to the parameters MIN and MAX. MIN indicates the lower inclusive bound of the range, while MAX indicateds the upper inclusive bound. The value will always be contained within the defined range once it’s constructed.

The condition MAX > MIN must be satified, or else the type can’t be constructed.

A default can be supplied by assigning a value to the parameter DEF. The default value must be contained by the range, meaning: MIN <= DEF <= MAX. Or else the type can’t be constructed.

It’s also required that either MIN to be greater than the primitive’s MIN or MAX to be lower than the primitive’s MAX, or else the type can’t be constructed.

Layout

ConstrainedU16 is guaranteed to have the same layout and ABI as u16

Examples

If the provided parameters satisfy the construction condition, associated constants and type constructors are acessible.

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

assert_eq!(Constrained::MIN, 1);
assert_eq!(Constrained::MAX, 254);
assert_eq!(Constrained::DEF, 1);

let constrained = Constrained::new(1)?;
assert_eq!(constrained.get(), 1);

Associated constants and type constructors are guarded against parameters that violate the MAX > MIN condition.

use constrained_int::u16::ConstrainedU16;

// MIN greater or equal to MAX does not satisfy the construction condition.
type InvalidRange = ConstrainedU16<254, 1>;

// None of these will compile for InvalidRange.
let value = InvalidRange::MIN;
let constrained = InvalidRange::default();
let constrained = InvalidRange::new_min();
/* ...other constructors */

Implementations

impl<const MIN: u16, const MAX: u16, const DEF: u16> ConstrainedU16<MIN, MAX, DEF>

where Guard<{ _ }>: Protect,

pub const MIN: u16 = MIN

The minimum inclusive value that this type can hold.

It’s assigned the MIN parameter value. Always satisfies the condition: MIN < MAX.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

assert_eq!(Constrained::MIN, 1);

pub const MAX: u16 = MAX

The maximum inclusive value that this type can hold.

It’s assigned the MAX parameter value. Always satisfies the condition: MAX > MIN.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

assert_eq!(Constrained::MAX, 254);

pub const DEF: u16 = DEF

The initialized value when constructed with default().

It’s assigned the DEF parameter value. Always satisfies the condition: MIN <= DEF <= MAX.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254, 254>;

assert_eq!(Constrained::DEF, 254);

pub const fn new(value: u16) -> Result<Self, ConstrainedU16Error<MIN, MAX>>

Creates a new instance with provided value, if it satifies the range’s inclusive bounds. If the provided value is out of bounds, an error is returned, indicating which bound was violated.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

let min = Constrained::new(1)?;
assert_eq!(min.get(), 1);

let max = Constrained::new(254)?;
assert_eq!(max.get(), 254);

// Out of inclusive bounds.
assert!(Constrained::new(0).is_err());
assert!(Constrained::new(255).is_err());

pub const fn saturating_new(value: u16) -> Self

Creates a new instance with provided value, if it satifies the range’s inclusive bounds. If provided value is out of bounds, the new instance is initialized with the value of the closest bound.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

// Below lower bound, so it constructs with lower bound value.
let min = Constrained::saturating_new(0);
assert_eq!(min.get(), 1);

// Above upper bound, so it constructs with upper bound value.
let max = Constrained::saturating_new(255);
assert_eq!(max.get(), 254);

pub const fn checked_new(value: u16) -> Option<Self>

Creates a new instance with provided value, if it satifies the range’s inclusive bounds. If provided value is out of bounds, a None is returned.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

let min = Constrained::checked_new(1).unwrap();
assert_eq!(min.get(), 1);

let max = Constrained::checked_new(254).unwrap();
assert_eq!(max.get(), 254);

// Out of inclusive bounds.
assert_eq!(None, Constrained::checked_new(0));
assert_eq!(None, Constrained::checked_new(255));

pub const fn new_min() -> Self

Creates a new instance with the value defined by the range’s lower bound.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

let min = Constrained::new_min();
assert_eq!(min.get(), 1);

pub const fn new_max() -> Self

Creates a new instance with the value defined by the range’s upper bound.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

let max = Constrained::new_max();
assert_eq!(max.get(), 254);

pub const fn range() -> RangeInclusive<u16>

Returns a RangeInclusive value corresponding to the type’s bondaries.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

let range = Constrained::range();
assert_eq!(Constrained::MIN, *range.start());
assert_eq!(Constrained::MAX, *range.end());

impl<const MIN: u16, const MAX: u16, const DEF: u16> ConstrainedU16<MIN, MAX, DEF>

pub fn set(&mut self, value: u16) -> Result<(), ConstrainedU16Error<MIN, MAX>>

Sets the contained value, if it satifies the range’s inclusive bounds. If the provided value is out of bounds, an error is returned, indicating which bound was violated.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

let mut constrained = Constrained::default();
assert_eq!(constrained.get(), 1);

constrained.set(254)?;
assert_eq!(constrained.get(), 254);

// Out of inclusive bounds.
assert!(constrained.set(0).is_err());
assert!(constrained.set(255).is_err());

assert_eq!(constrained.get(), 254);

pub const fn get(&self) -> u16

Returns the value of the contained integer type.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

let constrained = Constrained::default();
assert_eq!(constrained.get(), 1);

impl<const MIN: u16, const MAX: u16, const DEF: u16> ConstrainedU16<MIN, MAX, DEF>

pub const fn saturating_add(self, rhs: u16) -> Self

Saturating integer addition. Computes self + rhs, saturating the result at range’s upper bound.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

let mut constrained = Constrained::new_max();
// Saturates at upper bound.
constrained = constrained.saturating_add(1);
assert_eq!(constrained.get(), 254);

pub const fn saturating_add_signed(self, rhs: i16) -> Self

Saturating addition with a signed integer.

Computes self + rhs, saturating the result at the range’s upper bound if the integer is positive, or at the range’s lower bound if negative.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

let mut constrained = Constrained::new_min();
// Saturates at upper bound.
constrained = constrained.saturating_add_signed(-1);
assert_eq!(constrained.get(), 1);

pub const fn saturating_sub(self, rhs: u16) -> Self

Saturating integer substraction. Computes self - rhs, saturating the result at range’s lower bound.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

let mut constrained = Constrained::new_min();
// Saturates at lower bound.
constrained = constrained.saturating_sub(1);
assert_eq!(constrained.get(), 1);

pub const fn checked_add(self, rhs: u16) -> Option<Self>

Checked integer addition. Computes self + rhs, returning None if result is greater than range’s upper bound.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

let constrained = Constrained::new_max();
// Above upper bound.
assert_eq!(constrained.checked_add(1), None);

pub const fn checked_add_signed(self, rhs: i16) -> Option<Self>

Checked addition with a signed integer. Computes self + rhs, returning None if result is out of the range’s inclusive bounds.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

let constrained = Constrained::new_min();
// Below lower bound.
assert_eq!(constrained.checked_add_signed(-1), None);

pub const fn checked_sub(self, rhs: u16) -> Option<Self>

Checked integer substraction. Computes self - rhs, returning None if result is lower than range’s lower bound.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

let constrained = Constrained::new_min();
// Below lower bound.
assert_eq!(constrained.checked_sub(1), None);

pub const fn try_add(self, rhs: u16) -> Result<Self, MaxU16Error<MAX>>

Fallible integer addition. Computes self + rhs, returning an error if the result is greater than the range’s upper bound.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

let constrained = Constrained::new_max();
// Above upper bound.
assert!(constrained.try_add(1).is_err());

pub const fn try_add_signed( self, rhs: i16, ) -> Result<Self, ConstrainedU16Error<MIN, MAX>>

Fallible addition with signed integer. Computes self + rhs, returning an error if the result is out of the range’s inclusive bounds.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

let constrained = Constrained::new_min();
// Below upper bound.
assert!(constrained.try_add_signed(-1).is_err());

pub const fn try_sub(self, rhs: u16) -> Result<Self, MinU16Error<MIN>>

Fallible integer substraction. Computes self + rhs, returning an error if the result is lower than the range’s lower bound.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

let constrained = Constrained::new_min();
// Below lower bound.
assert!(constrained.try_sub(1).is_err());

pub const fn wrapping_add(self, rhs: u16) -> Self

Wrapping (modular) addition. Computes self + rhs, wrapping around at the range’s upper bound.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

let mut constrained = Constrained::new_max();
// Wraps around the upper bound.
constrained = constrained.wrapping_add(1);
assert_eq!(constrained.get(), Constrained::MIN);

pub const fn wrapping_add_signed(self, rhs: i16) -> Self

Wrapping (modular) addition with signed integer.

Computes self + rhs, wrapping the result around the range’s upper bound if the integer is positive, or at the range’s lower bound if negative.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

let mut constrained = Constrained::new_min();
// Wraps around the upper bound.
constrained = constrained.wrapping_add_signed(-1);
assert_eq!(constrained.get(), Constrained::MAX);

pub const fn wrapping_sub(self, rhs: u16) -> Self

Wrapping (modular) substraction. Computes self - rhs, wrapping around at the range’s lower bound.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

let mut constrained = Constrained::new_min();
// Wraps around the lower bound.
constrained = constrained.wrapping_sub(1);
assert_eq!(constrained.get(), Constrained::MAX);

pub const fn overflowing_add(self, rhs: u16) -> (Self, bool)

Wrapping (modular) addition, indicating if result was wrapped around.

Computes self + rhs, wrapping the result around the range’s upper bound. If a wrapping addition would have occurred, then the boolean is set to true, else to false.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

let mut constrained = Constrained::new_max();
let mut wrapped: bool;

// Wraps around the upper bound, the boolean is set to `true`.
(constrained, wrapped) = constrained.overflowing_add(1);
assert_eq!(constrained.get(), Constrained::MIN);
assert_eq!(wrapped, true);

pub const fn overflowing_add_signed(self, rhs: i16) -> (Self, bool)

Wrapping (modular) addition with signed integer, indicating if result was wrapped around.

Computes self + rhs, wrapping the result around the range’s upper bound if the integer is positive, or at the range’s lower bound if negative. If a wrapping addition would have occurred, then the boolean is set to true, else to false.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

let mut constrained = Constrained::new_min();
let mut wrapped: bool;

// Wraps around the lower bound, the boolean is set to `true`.
(constrained, wrapped) = constrained.overflowing_add_signed(-1);
assert_eq!(constrained.get(), Constrained::MAX);
assert_eq!(wrapped, true);

pub const fn overflowing_sub(self, rhs: u16) -> (Self, bool)

Wrapping (modular) substraction, indicating if result was wrapped around.

Computes self - rhs, wrapping the result around the range’s lower bound. If a wrapping substraction would have occurred, then the boolean is set to true, else to false.

Example

use constrained_int::u16::ConstrainedU16;

type Constrained = ConstrainedU16<1, 254>;

let mut constrained = Constrained::new_min();
let mut wrapped: bool;

// Wraps around the lower bound, the boolean is set to `true`.
(constrained, wrapped) = constrained.overflowing_sub(1);
assert_eq!(constrained.get(), Constrained::MAX);
assert_eq!(wrapped, true);

Trait Implementations

impl<const MIN: u16, const MAX: u16, const DEF: u16> Binary for ConstrainedU16<MIN, MAX, DEF>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<const MIN: u16, const MAX: u16, const DEF: u16> Clone for ConstrainedU16<MIN, MAX, DEF>

fn clone(&self) -> ConstrainedU16<MIN, MAX, DEF>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<const MIN: u16, const MAX: u16, const DEF: u16> Debug for ConstrainedU16<MIN, MAX, DEF>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<const MIN: u16, const MAX: u16, const DEF: u16> Default for ConstrainedU16<MIN, MAX, DEF>

where Guard<{ _ }>: Protect,

fn default() -> Self

Returns the “default value” for a type.

impl<'de, const MIN: u16, const MAX: u16, const DEF: u16> Deserialize<'de> for ConstrainedU16<MIN, MAX, DEF>

Available on crate feature serde only.

fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl<const MIN: u16, const MAX: u16, const DEF: u16> Display for ConstrainedU16<MIN, MAX, DEF>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<const MIN: u16, const MAX: u16, const DEF: u16> Hash for ConstrainedU16<MIN, MAX, DEF>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<const MIN: u16, const MAX: u16, const DEF: u16> LowerHex for ConstrainedU16<MIN, MAX, DEF>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<const MIN: u16, const MAX: u16, const DEF: u16> Octal for ConstrainedU16<MIN, MAX, DEF>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<const MIN: u16, const MAX: u16, const DEF: u16> Ord for ConstrainedU16<MIN, MAX, DEF>

fn cmp(&self, other: &ConstrainedU16<MIN, MAX, DEF>) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<const MIN: u16, const MAX: u16, const DEF: u16> PartialEq for ConstrainedU16<MIN, MAX, DEF>

fn eq(&self, other: &ConstrainedU16<MIN, MAX, DEF>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<const MIN: u16, const MAX: u16, const DEF: u16> PartialOrd for ConstrainedU16<MIN, MAX, DEF>

fn partial_cmp(&self, other: &ConstrainedU16<MIN, MAX, DEF>) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<const MIN: u16, const MAX: u16, const DEF: u16> RangeBounds<u16> for ConstrainedU16<MIN, MAX, DEF>

fn start_bound(&self) -> Bound<&u16>

Start index bound.

fn end_bound(&self) -> Bound<&u16>

End index bound.

fn contains<U>(&self, item: &U) -> bool

where T: PartialOrd<U>, U: PartialOrd<T> + ?Sized,

Returns true if item is contained in the range.

fn is_empty(&self) -> bool

where T: PartialOrd,

🔬This is a nightly-only experimental API. (range_bounds_is_empty)

Returns true if the range contains no items. One-sided ranges (RangeFrom, etc) always return false.

impl<const MIN: u16, const MAX: u16, const DEF: u16> Serialize for ConstrainedU16<MIN, MAX, DEF>

Available on crate feature serde only.

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.

impl<const MIN: u16, const MAX: u16, const DEF: u16> TryFrom<u16> for ConstrainedU16<MIN, MAX, DEF>

where Guard<{ _ }>: Protect,

type Error = ConstrainedU16Error<MIN, MAX>

The type returned in the event of a conversion error.

fn try_from(value: u16) -> Result<Self, Self::Error>

Performs the conversion.

impl<const MIN: u16, const MAX: u16, const DEF: u16> UpperHex for ConstrainedU16<MIN, MAX, DEF>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<const MIN: u16, const MAX: u16, const DEF: u16> Copy for ConstrainedU16<MIN, MAX, DEF>

impl<const MIN: u16, const MAX: u16, const DEF: u16> Eq for ConstrainedU16<MIN, MAX, DEF>

impl<const MIN: u16, const MAX: u16, const DEF: u16> StructuralPartialEq for ConstrainedU16<MIN, MAX, DEF>