#[repr(transparent)]
pub struct ConstrainedI32<const MIN: i32, const MAX: i32, const DEF: i32 = MIN>(_);
Expand description

An i32 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.

Examples

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

use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

assert_eq!(Constrained::MIN, -127);
assert_eq!(Constrained::MAX, 126);
assert_eq!(Constrained::DEF, -127);

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

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

use constrained_int::i32::ConstrainedI32;

// MIN greater or equal to MAX does not satisfy the construction condition.
type InvalidRange = ConstrainedI32<126, -127>;

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

Implementations

The minimum inclusive value that this type can hold.

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

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

assert_eq!(Constrained::MIN, -127);

The maximum inclusive value that this type can hold.

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

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

assert_eq!(Constrained::MAX, 126);

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::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126, 126>;

assert_eq!(Constrained::DEF, 126);

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::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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

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

// Out of inclusive bounds.
assert!(Constrained::new(-128).is_err());
assert!(Constrained::new(127).is_err());

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::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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

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

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::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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

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

// Out of inclusive bounds.
assert_eq!(None, Constrained::checked_new(-128));
assert_eq!(None, Constrained::checked_new(127));

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

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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

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

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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

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

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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

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::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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

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

// Out of inclusive bounds.
assert!(constrained.set(-128).is_err());
assert!(constrained.set(127).is_err());

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

Returns the value of the contained integer type.

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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

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

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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

constrained = Constrained::new_min();
// Saturates at lower bound.
constrained = constrained.saturating_add(-1);
assert_eq!(constrained.get(), -127);

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

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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

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

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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

constrained = Constrained::new_max();
// Saturates at upper bound.
constrained = constrained.saturating_sub(-1);
assert_eq!(constrained.get(), 126);

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

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

let mut constrained = Constrained::new_min();
// Saturates at the lower bound.
constrained = constrained.saturating_sub_unsigned(1_u32);
assert_eq!(constrained.get(), -127);

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

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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

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

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

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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

Checked integer substraction. Computes self - rhs, returning None if result is out of the range’s inclusive bounds.

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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

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

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

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

let mut constrained = Constrained::new_min();
// Above upper bound.
assert_eq!(constrained.checked_sub_unsigned(1_u32), None);

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

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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

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

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

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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

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

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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

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

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

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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

Wrapping (modular) addition.

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::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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

constrained = Constrained::new_min();
// Wraps around lower bound.
constrained = constrained.wrapping_add(-1);
assert_eq!(constrained.get(), Constrained::MAX);

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

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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

Wrapping (modular) substraction.

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

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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

constrained = Constrained::new_max();
// Wraps around upper bound.
constrained = constrained.wrapping_sub(-1);
assert_eq!(constrained.get(), Constrained::MIN);

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

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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

Wrapping (modular) addition, 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::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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(2);
assert_eq!(constrained.get(), Constrained::MIN + 1);
assert_eq!(wrapped, true);

// Addition is within range bounds, the boolean is set to `false`.
(constrained, wrapped) = constrained.overflowing_add(-1);
assert_eq!(constrained.get(), Constrained::MIN);
assert_eq!(wrapped, false);

Wrapping (modular) addition with unsigned integer, 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::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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_unsigned(1_u32);
assert_eq!(constrained.get(), Constrained::MIN);
assert_eq!(wrapped, true);

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

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

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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(2);
assert_eq!(constrained.get(), Constrained::MAX - 1);
assert_eq!(wrapped, true);

// Substraction is within range bounds, the boolean is set to `false`.
(constrained, wrapped) = constrained.overflowing_sub(-1);
assert_eq!(constrained.get(), Constrained::MAX);
assert_eq!(wrapped, false);

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

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

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

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

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

Returns a number representing sign of self.

  • 0 if the number is zero
  • 1 if the number is positive
  • -1 if the number is negative
Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;

let mut constrained = Constrained::new_min();
assert_eq!(constrained.signum(), -1);

constrained = Constrained::new_max();
assert_eq!(constrained.signum(), 1);

constrained.set(0).unwrap();
assert_eq!(constrained.signum(), 0);

Returns true if self is negative and false if the number is zero or positive.

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;
let mut constrained = Constrained::new_min();
assert!(constrained.is_negative());

Returns true if self is positive and false if the number is zero or negative.

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-127, 126>;
let mut constrained = Constrained::new_max();
assert!(constrained.is_positive());

Checked absolute value. Computes i32::abs(), returning None if it’s greater than MAX.

Example
use constrained_int::i32::ConstrainedI32;

type Constrained = ConstrainedI32<-10, 8>;
let mut constrained = Constrained::new(-5).unwrap();
// Lower than `MAX`.
constrained = constrained.checked_abs().unwrap();
assert_eq!(constrained.get(), 5);

// Greater than `MAX`.
constrained.set(-9).unwrap();
assert_eq!(constrained.checked_abs(), None);

Trait Implementations

Formats the value using the given formatter.

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Deserialize this value from the given Serde deserializer. Read more

Formats the value using the given formatter. Read more

Feeds this value into the given Hasher. Read more

Feeds a slice of this type into the given Hasher. Read more

Formats the value using the given formatter.

Formats the value using the given formatter.

This method returns an Ordering between self and other. Read more

Compares and returns the maximum of two values. Read more

Compares and returns the minimum of two values. Read more

Restrict a value to a certain interval. Read more

This method tests for self and other values to be equal, and is used by ==. Read more

This method tests for !=.

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

This method tests less than (for self and other) and is used by the < operator. Read more

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more

This method tests greater than (for self and other) and is used by the > operator. Read more

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

Start index bound. Read more

End index bound. Read more

Returns true if item is contained in the range. Read more

Serialize this value into the given Serde serializer. Read more

The type returned in the event of a conversion error.

Performs the conversion.

Formats the value using the given formatter.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

Uses borrowed data to replace owned data, usually by cloning. Read more

Converts the given value to a String. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.