pub struct UnitInterval<T>(/* private fields */);
Expand description
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§
Source§impl<T: Zero + One + PartialOrd> UnitInterval<T>
impl<T: Zero + One + PartialOrd> UnitInterval<T>
Sourcepub fn new_checked(val: T) -> Result<Self, BoundError<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.
Sourcepub fn new_clamped(val: T) -> Self
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);
Source§impl<T: FloatCore> UnitInterval<T>
impl<T: FloatCore> UnitInterval<T>
Source§impl<T> UnitInterval<T>
impl<T> UnitInterval<T>
Sourcepub const unsafe fn new_unchecked(val: T) -> Self
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.
Sourcepub fn into_inner(self) -> T
pub fn into_inner(self) -> T
Consumes the UnitInterval
and returns the inner value.
Source§impl<T: Zero> UnitInterval<T>
impl<T: Zero> UnitInterval<T>
Source§impl<T: One> UnitInterval<T>
impl<T: One> UnitInterval<T>
Sourcepub fn one() -> Self
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);
Sourcepub fn complement(self) -> UnitInterval<<T as Sub>::Output>where
T: Sub,
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));
Source§impl<T: Add> UnitInterval<T>
impl<T: Add> UnitInterval<T>
Sourcepub fn checked_add(
self,
rhs: Self,
) -> Result<UnitInterval<T::Output>, BoundError<T::Output>>
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);
Sourcepub fn clamped_add(self, rhs: Self) -> UnitInterval<T::Output>
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);
Source§impl<T: Sub> UnitInterval<T>
impl<T: Sub> UnitInterval<T>
Sourcepub fn checked_sub(
self,
rhs: Self,
) -> Result<UnitInterval<T::Output>, BoundError<T::Output>>
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);
Sourcepub fn clamped_sub(self, rhs: Self) -> UnitInterval<T::Output>
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);
Source§impl<T: Mul> UnitInterval<T>
impl<T: Mul> UnitInterval<T>
Sourcepub fn checked_mul(
self,
rhs: Self,
) -> Result<UnitInterval<T::Output>, BoundError<T::Output>>
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);
Sourcepub fn clamped_mul(self, rhs: Self) -> UnitInterval<T::Output>
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);
Source§impl<T: Div> UnitInterval<T>
impl<T: Div> UnitInterval<T>
Sourcepub fn checked_div(
self,
rhs: Self,
) -> Result<UnitInterval<T::Output>, BoundError<T::Output>>
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);
Sourcepub fn clamped_div(self, rhs: Self) -> UnitInterval<T::Output>
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§
Source§impl<T: Add> Add<T> for UnitInterval<T>
impl<T: Add> Add<T> for UnitInterval<T>
Source§impl<T: Add> Add for UnitInterval<T>
impl<T: Add> Add for UnitInterval<T>
Source§impl<T> AsRef<T> for UnitInterval<T>
impl<T> AsRef<T> for UnitInterval<T>
Source§impl<T> Borrow<T> for UnitInterval<T>
impl<T> Borrow<T> for UnitInterval<T>
Source§impl<T: Clone> Clone for UnitInterval<T>
impl<T: Clone> Clone for UnitInterval<T>
Source§fn clone(&self) -> UnitInterval<T>
fn clone(&self) -> UnitInterval<T>
1.0.0 · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read more