Struct UnitInterval

pub struct UnitInterval<T>(/* private fields */);

A number in the closed unit interval [0, 1]

The precise invariant is that for an underlying value v of type T is T::zero() <= v and v <= T::one() where Zero and One are traits from from the [num-traits] crate.

Unlike NonZero types, this type does not reserve any bit-patterns and simply guarantee that the value inside will not exceed the bounds via construction. Unsoundly constructing a value of this type that exceed its bounds will not result in immediate undefined behavior.

Examples

use unit_interval::UnitInterval;

let full = UnitInterval::one();
let half = UnitInterval::new(0.5);

assert_eq!(full + half, 1.5);
assert_eq!(half - full, -0.5);
assert_eq!(half * full, UnitInterval::new(0.5));
assert_eq!(full / half, 2.0);

assert_eq!(full.into_inner(), 1.0);
assert_eq!(half.into_inner(), 0.5);

Implementations

impl<T: Zero + One + PartialOrd> UnitInterval<T>

pub fn new_checked(val: T) -> Result<Self, BoundError<T>>

Guarantee the number in the closed unit interval if T::zero() <= val and val <= T::one(), else returns an error detailing which bound was crossed.

pub fn new_clamped(val: T) -> Self

Guarantee the number in the closed unit interval, clamping the value if it exceed the bounds in either direction.

Panics

Panics if the value exceed the bounds in both direction (see BoundErrorKind::Neither).

Examples

use unit_interval::UnitInterval;

assert_eq!(UnitInterval::new_clamped(2).into_inner(), 1);
assert_eq!(UnitInterval::new_clamped(-5).into_inner(), 0);

NaN is an example of when this function panics

use unit_interval::UnitInterval;

let _ = UnitInterval::new_clamped(f32::NAN);

pub fn new(val: T) -> Self

where T: Debug,

Guarantee the number in the closed unit interval, panicking if not.

Panics

Panics if the number is not within the unit interval.

impl<T: FloatCore> UnitInterval<T>

pub fn new_fract(val: T) -> Self

Guarantee the number in the closed unit interval by taking only its fractional part.

This cannot fail as the fractional part of a number is off the range [0, 1), which is a subset of [0, 1].

impl<T> UnitInterval<T>

pub const unsafe fn new_unchecked(val: T) -> Self

Assumes that the number is in the closed unit interval.

Safety

Improper usage of this function should only lead to logic error and not undefined behavior as long as no further unsafe code rely on the guarantee granted by this type.

pub const fn as_inner(&self) -> &T

Returns a reference to the inner value.

pub fn into_inner(self) -> T

Consumes the UnitInterval and returns the inner value.

impl<T: Zero> UnitInterval<T>

pub fn zero() -> Self

Creates a new UnitInterval with a value of zero.

Examples

use unit_interval::UnitInterval;

let zero = UnitInterval::<f32>::zero();
assert_eq!(zero.into_inner(), 0.0);

impl<T: One> UnitInterval<T>

pub fn one() -> Self

Creates a new UnitInterval with a value of one.

Examples

use unit_interval::UnitInterval;

let one = UnitInterval::<f32>::one();
assert_eq!(one.into_inner(), 1.0);

pub fn complement(self) -> UnitInterval<<T as Sub>::Output>

where T: Sub,

Returns the complement of the currently held value.

Examples

use unit_interval::UnitInterval;

let a = UnitInterval::new(0.2);
assert_eq!(a.complement(), UnitInterval::new(0.8));

impl<T: Add> UnitInterval<T>

where T::Output: Zero + One + PartialOrd,

pub fn checked_add( self, rhs: Self, ) -> Result<UnitInterval<T::Output>, BoundError<T::Output>>

Adds a value inside the close unit interval to produce another.

Equivalent to adding the inner values then using UnitInterval::new_checked.

Examples

use unit_interval::{UnitInterval, BoundErrorKind};

let a = UnitInterval::new(0.5);
let b = UnitInterval::new(0.75);
let result = a.checked_add(b);
assert_eq!(result, UnitInterval::new_checked(0.5 + 0.75));
let err = result.unwrap_err();
assert_eq!(err.kind(), BoundErrorKind::GreaterThanOne);
assert_eq!(err.value(), 1.25);

pub fn clamped_add(self, rhs: Self) -> UnitInterval<T::Output>

Adds two UnitInterval values, clamping the result to the unit interval.

Examples

use unit_interval::UnitInterval;

let a = UnitInterval::new(0.7);
let b = UnitInterval::new(0.6);
let result = a.clamped_add(b);
assert_eq!(result.into_inner(), 1.0);

impl<T: Sub> UnitInterval<T>

where T::Output: Zero + One + PartialOrd,

pub fn checked_sub( self, rhs: Self, ) -> Result<UnitInterval<T::Output>, BoundError<T::Output>>

Subtracts a value inside the close unit interval to produce another.

Equivalent to subtracting the inner values then using UnitInterval::new_checked.

Examples

use unit_interval::{UnitInterval, BoundErrorKind};

let a = UnitInterval::new(0.4);
let b = UnitInterval::new(0.8);
let result = a.checked_sub(b);
assert_eq!(result, UnitInterval::new_checked(0.4 - 0.8));
let err = result.unwrap_err();
assert_eq!(err.kind(), BoundErrorKind::LessThanZero);
assert_eq!(err.value(), -0.4);

pub fn clamped_sub(self, rhs: Self) -> UnitInterval<T::Output>

Subtracts one UnitInterval from another, clamping the result to the unit interval.

Examples

use unit_interval::UnitInterval;

let a = UnitInterval::new(0.3);
let b = UnitInterval::new(0.6);
let result = a.clamped_sub(b);
assert_eq!(result.into_inner(), 0.0);

impl<T: Mul> UnitInterval<T>

where T::Output: Zero + One + PartialOrd,

pub fn checked_mul( self, rhs: Self, ) -> Result<UnitInterval<T::Output>, BoundError<T::Output>>

Multiplies a value inside the close unit interval to produce another.

Equivalent to multiplying the inner values then using UnitInterval::new_checked.

Note: Multiplication of two values in [0, 1] always results in a value in [0, 1], so checking is not strictly necessary for this operation.

Examples

use unit_interval::UnitInterval;

let a = UnitInterval::new(0.5);
let b = UnitInterval::new(0.6);
let result = a.checked_mul(b);
assert_eq!(result, UnitInterval::new_checked(0.5 * 0.6));
let ok = result.unwrap();
assert_eq!(ok.into_inner(), 0.3);

pub fn clamped_mul(self, rhs: Self) -> UnitInterval<T::Output>

Multiplies two UnitInterval values, clamping the result to the unit interval.

Note: Multiplication of two values in [0, 1] always results in a value in [0, 1], so clamping is not strictly necessary for this operation.

Examples

use unit_interval::UnitInterval;

let a = UnitInterval::new(0.5);
let b = UnitInterval::new(0.6);
let result = a.clamped_mul(b);
assert_eq!(result.into_inner(), 0.3);

impl<T: Div> UnitInterval<T>

where T::Output: Zero + One + PartialOrd,

pub fn checked_div( self, rhs: Self, ) -> Result<UnitInterval<T::Output>, BoundError<T::Output>>

Divides a value inside the close unit interval to produce another.

Equivalent to dividing the inner values then using UnitInterval::new_checked.

Examples

use unit_interval::{UnitInterval, BoundErrorKind};

let a = UnitInterval::new(0.8);
let b = UnitInterval::new(0.4);
let result = a.checked_div(b);
assert_eq!(result, UnitInterval::new_checked(0.8 / 0.4));
let err = result.unwrap_err();
assert_eq!(err.kind(), BoundErrorKind::GreaterThanOne);
assert_eq!(err.value(), 2.0);

pub fn clamped_div(self, rhs: Self) -> UnitInterval<T::Output>

Divides one UnitInterval by another, clamping the result to the unit interval.

Examples

use unit_interval::UnitInterval;

let a = UnitInterval::new(0.8);
let b = UnitInterval::new(0.4);
let result = a.clamped_div(b);
assert_eq!(result.into_inner(), 1.0);

Trait Implementations

impl<T: Add> Add<T> for UnitInterval<T>

type Output = <T as Add>::Output

The resulting type after applying the + operator.

fn add(self, rhs: T) -> Self::Output

Performs the + operation.

impl<T: Add> Add for UnitInterval<T>

type Output = <T as Add>::Output

The resulting type after applying the + operator.

fn add(self, rhs: Self) -> Self::Output

Performs the + operation.

impl<T> AsRef<T> for UnitInterval<T>

fn as_ref(&self) -> &T

Converts this type into a shared reference of the (usually inferred) input type.

impl<T> Borrow<T> for UnitInterval<T>

fn borrow(&self) -> &T

Immutably borrows from an owned value.

impl<T: Clone> Clone for UnitInterval<T>

fn clone(&self) -> UnitInterval<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for UnitInterval<T>

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

Formats the value using the given formatter.

impl<T: Div> Div<T> for UnitInterval<T>

type Output = <T as Div>::Output

The resulting type after applying the / operator.

fn div(self, rhs: T) -> Self::Output

Performs the / operation.

impl<T: Div> Div for UnitInterval<T>

type Output = <T as Div>::Output

The resulting type after applying the / operator.

fn div(self, rhs: Self) -> Self::Output

Performs the / operation.

impl<T: Hash> Hash for UnitInterval<T>

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<T: Mul> Mul<T> for UnitInterval<T>

type Output = <T as Mul>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: T) -> Self::Output

Performs the * operation.

impl<T: Mul> Mul for UnitInterval<T>

type Output = UnitInterval<<T as Mul>::Output>

The resulting type after applying the * operator.

fn mul(self, rhs: UnitInterval<T>) -> Self::Output

Performs the * operation.

impl<T: One> One for UnitInterval<T>

fn one() -> Self

Returns the multiplicative identity element of Self, 1.

fn set_one(&mut self)

Sets self to the multiplicative identity element of Self, 1.

fn is_one(&self) -> bool

where Self: PartialEq,

Returns true if self is equal to the multiplicative identity.

impl<T: Ord> Ord for UnitInterval<T>

fn cmp(&self, other: &UnitInterval<T>) -> 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<T: PartialEq> PartialEq for UnitInterval<T>

fn eq(&self, other: &UnitInterval<T>) -> 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<T: PartialOrd> PartialOrd for UnitInterval<T>

fn partial_cmp(&self, other: &UnitInterval<T>) -> 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<T: Sub> Sub<T> for UnitInterval<T>

type Output = <T as Sub>::Output

The resulting type after applying the - operator.

fn sub(self, rhs: T) -> Self::Output

Performs the - operation.

impl<T: Sub> Sub for UnitInterval<T>

type Output = <T as Sub>::Output

The resulting type after applying the - operator.

fn sub(self, rhs: Self) -> Self::Output

Performs the - operation.

impl<T: Copy> Copy for UnitInterval<T>

impl<T: Eq> Eq for UnitInterval<T>

impl<T> StructuralPartialEq for UnitInterval<T>