Struct UnitInterval

Source
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>

Source

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.

Source

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

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.

Source§

impl<T: FloatCore> UnitInterval<T>

Source

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].

Source§

impl<T> UnitInterval<T>

Source

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.

Source

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

Returns a reference to the inner value.

Source

pub fn into_inner(self) -> T

Consumes the UnitInterval and returns the inner value.

Source§

impl<T: Zero> UnitInterval<T>

Source

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);
Source§

impl<T: One> UnitInterval<T>

Source

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);
Source

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>
where T::Output: Zero + One + PartialOrd,

Source

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);
Source

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>
where T::Output: Zero + One + PartialOrd,

Source

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);
Source

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>
where T::Output: Zero + One + PartialOrd,

Source

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);
Source

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>
where T::Output: Zero + One + PartialOrd,

Source

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);
Source

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>

Source§

type Output = <T as Add>::Output

The resulting type after applying the + operator.
Source§

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

Performs the + operation. Read more
Source§

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

Source§

type Output = <T as Add>::Output

The resulting type after applying the + operator.
Source§

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

Performs the + operation. Read more
Source§

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

Source§

fn as_ref(&self) -> &T

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

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

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

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

Source§

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

Returns a duplicate of the value. Read more
1.0.0 · Source§

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

Performs copy-assignment from source. Read more
Source§

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

Source§

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

Formats the value using the given formatter. Read more
Source§

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

Source§

type Output = <T as Div>::Output

The resulting type after applying the / operator.
Source§

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

Performs the / operation. Read more
Source§

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

Source§

type Output = <T as Div>::Output

The resulting type after applying the / operator.
Source§

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

Performs the / operation. Read more
Source§

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

Source§

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

Feeds this value into the given Hasher. Read more
1.3.0 · Source§

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

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

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

Source§

type Output = <T as Mul>::Output

The resulting type after applying the * operator.
Source§

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

Performs the * operation. Read more
Source§

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

Source§

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

The resulting type after applying the * operator.
Source§

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

Performs the * operation. Read more
Source§

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

Source§

fn one() -> Self

Returns the multiplicative identity element of Self, 1. Read more
Source§

fn set_one(&mut self)

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

fn is_one(&self) -> bool
where Self: PartialEq,

Returns true if self is equal to the multiplicative identity. Read more
Source§

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

Source§

fn cmp(&self, other: &UnitInterval<T>) -> Ordering

This method returns an Ordering between self and other. Read more
1.21.0 · Source§

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

Compares and returns the maximum of two values. Read more
1.21.0 · Source§

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

Compares and returns the minimum of two values. Read more
1.50.0 · Source§

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

Restrict a value to a certain interval. Read more
Source§

impl<T: PartialEq> PartialEq for UnitInterval<T>

Source§

fn eq(&self, other: &UnitInterval<T>) -> bool

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

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

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

impl<T: PartialOrd> PartialOrd for UnitInterval<T>

Source§

fn partial_cmp(&self, other: &UnitInterval<T>) -> Option<Ordering>

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

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

Tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · Source§

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

Tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 · Source§

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

Tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · Source§

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

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

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

Source§

type Output = <T as Sub>::Output

The resulting type after applying the - operator.
Source§

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

Performs the - operation. Read more
Source§

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

Source§

type Output = <T as Sub>::Output

The resulting type after applying the - operator.
Source§

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

Performs the - operation. Read more
Source§

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

Source§

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

Source§

impl<T> StructuralPartialEq for UnitInterval<T>

Auto Trait Implementations§

§

impl<T> Freeze for UnitInterval<T>
where T: Freeze,

§

impl<T> RefUnwindSafe for UnitInterval<T>
where T: RefUnwindSafe,

§

impl<T> Send for UnitInterval<T>
where T: Send,

§

impl<T> Sync for UnitInterval<T>
where T: Sync,

§

impl<T> Unpin for UnitInterval<T>
where T: Unpin,

§

impl<T> UnwindSafe for UnitInterval<T>
where T: UnwindSafe,

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

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

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

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

fn clone_into(&self, target: &mut T)

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

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.