Enum Interval 

pub enum Interval<T>
where
    T: PartialOrd,
{
    TwoSided(T, T),
    UpperOneSided(T),
    LowerOneSided(T),
}

Interval over a partially ordered type (NB: floating point numbers are only partially ordered because of NaN values). The interval is defined by its lower and upper bounds. One-sided intervals (with a single concrete bound) are also supported. In this crate, intervals are considered inclusive of their (finite) bounds.

Type parameters

• T: The type over which the interval is defined. It must be partially ordered.

Variants

• TwoSided(T, T): Two-sided interval with lower and upper bounds. The interval is defined as [low, high]. The bounds are included in the interval.
• UpperOneSided(T): Upper one-sided interval with a lower bound. The interval is defined as [low, +∞). The lower bound is included in the interval.
• LowerOneSided(T): Lower one-sided interval with an upper bound. The interval is defined as (-∞, high]. The upper bound is included in the interval.

Intervals support various operations that depend on the type T over which they are defined.

Operations

Creation

• Self::new(low, high): Create a new interval from its left and right bounds for ordered types with equality.
• Self::new_upper(low): Create a new upper one-sided interval from its left bound.
• Self::new_lower(high): Create a new lower one-sided interval from its right bound.

Accessors

• Self::low(): Get the lower bound of the interval (if any) for partially ordered types.
• Self::high(): Get the upper bound of the interval (if any) for partially ordered types.
• Self::low_f(): Get the lower bound of the interval (if any) for floating point types.
• Self::high_f(): Get the upper bound of the interval (if any) for floating point types.
• Self::low_i(): Get the lower bound of the interval (if any) for signed integer types.
• Self::high_i(): Get the upper bound of the interval (if any) for signed integer types.
• Self::low_u(): Get the lower bound of the interval (if any) for unsigned integer types.
• Self::high_u(): Get the upper bound of the interval (if any) for unsigned integer types.
• Self::low_as_ref(): Get a reference to the lower bound of the interval (if any).
• Self::high_as_ref(): Get a reference to the upper bound of the interval (if any).
• Self::left(): Get the left bound of the interval (if any).
• Self::right(): Get the right bound of the interval (if any).

Characteristics

• Self::is_two_sided(): Test whether the interval is two-sided.
• Self::is_one_sided(): Test whether the interval is one-sided.
• Self::is_upper(): Test whether the interval is an upper one-sided interval.
• Self::is_lower(): Test whether the interval is a lower one-sided interval.
• Self::is_degenerate(): Test whether the interval is degenerate.

Comparison

• Self::intersects(other): Test whether the interval intersects another interval.
• Self::is_included_in(other): Test whether the interval is included in another interval.
• Self::includes(other): Test whether the interval includes another interval.
• Self::contains(x): Test whether the interval contains a value.
• approximate equality with approx if the approx feature is enabled.

Operators with a scalar value

• Self::mul(rhs): Multiply the interval by a value.
• Self::div(rhs): Divide the interval by a value.
• Self::add(rhs): Add a value to the interval.
• Self::sub(rhs): Subtract a value from the interval.

Operators with another interval

• Self::relative_to(reference): Given two intervals, compute the relative interval compared to the reference (argument). The relative interval is defined as the interval of the ratios of the two intervals.

Conversions

• Self::try_from(value): Create a new interval from a tuple of bounds. The first element of the tuple is the lower bound, the second element is the upper bound. If the lower bound is greater than the upper bound, an error is returned.
• Self::from(range): Create a new interval from a range. The range must be bounded. If the lower bound is greater than the upper bound, an error is returned.

Display

• Self::fmt(): Format the interval as a string.

Examples

Creation

use stats_ci::*;
let interval = Interval::new(0., 10.)?;
let interval = Interval::new_upper(0.);
let interval = Interval::new_lower(10.);

Accessors

let interval = Interval::new(0., 10.)?;
assert_eq!(interval.low(), Some(0.));
assert_eq!(interval.high(), Some(10.));
assert_eq!(interval.low_f(), 0.);
assert_eq!(interval.high_f(), 10.);
assert_eq!(interval.width(), Some(10.));
assert_eq!(interval.is_one_sided(), false);
assert_eq!(interval.is_two_sided(), true);
assert_eq!(interval.is_upper(), false);
assert_eq!(interval.is_lower(), false);
assert_eq!(interval.is_degenerate(), false);

Comparison

let interval = Interval::new(0., 10.)?;
let interval2 = Interval::new(8., 15.)?;
let interval3 = Interval::new(2., 5.)?;
assert!(interval.intersects(&interval2));
assert!(interval3.is_included_in(&interval));
assert!(interval.includes(&interval3));
assert!(interval3 < interval2);
assert!(interval == Interval::new(0., 10.)?);
assert!(interval.contains(&5.));
assert!(!interval.contains(&20.));

Operations

let interval = Interval::new(2., 4.)?;
assert_eq!(interval * 2., Interval::new(4., 8.)?);
assert_eq!(interval + 2., Interval::new(4., 6.)?);
assert_eq!(interval - 2., Interval::new(0., 2.)?);
assert_eq!(interval / 2., Interval::new(1., 2.)?);

Conversions

let interval = Interval::new(2., 4.)?;
assert_eq!(interval, Interval::try_from(2. ..= 4.)?);
assert_eq!(interval, Interval::try_from((2., 4.))?);
assert_eq!(interval, Interval::try_from((Some(2.), Some(4.)))?);
assert_eq!(Interval::from(..= 10.), Interval::new_lower(10.));
assert_eq!(Interval::from(2. ..), Interval::new_upper(2.));
assert_eq!(format!("{}", interval), String::from("[2, 4]"));
assert_eq!(format!("{}", Interval::new_lower(3.)), String::from("(<-,3]"));
assert_eq!(format!("{}", Interval::new_upper(2.)), String::from("[2,->)"));

Variants

TwoSided(T, T)

Two-sided interval with lower and upper bounds. The interval is defined as [low, high]. The bounds are included in the interval.

UpperOneSided(T)

Upper one-sided interval with a lower bound. The interval is defined as [low, +∞). The lower bound is included in the interval.

LowerOneSided(T)

Lower one-sided interval with an upper bound. The interval is defined as (-∞, high]. The upper bound is included in the interval.

Implementations

impl<T: PartialOrd> Interval<T>

pub fn new(low: T, high: T) -> Result<Self, IntervalError>

Create a new interval from its left and right bounds for ordered types with equality.

Examples

let interval = Interval::new(0., 1.)?;
assert_eq!(interval.low(), Some(0.));
assert_eq!(interval.high(), Some(1.));
let interval2 = Interval::new("A", "Z")?;
assert_eq!(interval2.low(), Some("A"));
assert_eq!(interval2.high(), Some("Z"));
let interval3 = Interval::new(0, 0_usize)?;
assert_eq!(interval3.low(), Some(0));
assert_eq!(interval3.high(), Some(0));

pub fn new_upper(low: T) -> Self

Create a new upper one-sided interval from its left bound. The interval is defined as [low, +∞). The bound is included in the interval.

Examples

The interval below represents [0., +∞).

let interval = Interval::new_upper(0.);
assert_eq!(interval.low(), Some(0.));
assert_eq!(interval.high(), None);

pub fn new_lower(high: T) -> Self

Create a new lower one-sided interval from its right bound. The interval is defined as (-∞, high]. The bound is included in the interval.

Examples

The interval below represents (-∞, 1.]

let interval = Interval::new_lower(1.);
assert_eq!(interval.low(), None);
assert_eq!(interval.high(), Some(1.));

pub fn is_two_sided(&self) -> bool

Test whether the interval is two-sided.

pub fn is_one_sided(&self) -> bool

Test whether the interval is one-sided.

pub fn is_upper(&self) -> bool

Test whether the interval is an upper one-sided interval.

pub fn is_lower(&self) -> bool

Test whether the interval is a lower one-sided interval.

pub fn contains(&self, x: &T) -> bool

Test whether the interval contains a value.

Examples

let interval = Interval::new(0., 1.)?;
assert!(interval.contains(&0.5));
assert!(!interval.contains(&2.));

pub fn intersects(&self, other: &Self) -> bool

Test whether the interval intersects another interval. Two intervals are considered to intersect even if they only have a single point in common (e.g., one of their bounds).

Examples

let interval = Interval::new(0., 1.)?;
let interval2 = Interval::new(0.5, 1.5)?;
assert!(interval.intersects(&interval2));
let interval3 = Interval::new(2., 3.)?;
assert!(!interval.intersects(&interval3));

pub fn is_included_in(&self, other: &Self) -> bool

Test whether the interval is included in another interval.

The inclusion is not strict, i.e. an interval is included in itself.

pub fn includes(&self, other: &Self) -> bool

Test whether the interval includes another interval.

The inclusion is not strict, i.e. an interval includes itself.

pub fn left(&self) -> Option<&T>

Get the left bound of the interval (if any).

pub fn right(&self) -> Option<&T>

Get the right bound of the interval (if any).

impl<T: PartialOrd + PartialEq> Interval<T>

pub fn is_degenerate(&self) -> bool

Test whether the interval is degenerate. A degenerate interval is an interval with a single point. For example, the interval [0, 0] is degenerate.

impl<T: PartialOrd + Clone> Interval<T>

pub fn low(&self) -> Option<T>

Get the lower bound of the interval (if any) for partially ordered types.

This function clones the bound. If cloning is an issue, use Self::low_as_ref() instead.

pub fn high(&self) -> Option<T>

Get the upper bound of the interval (if any) for partially ordered types.

This function clones the bound. If cloning is an issue, use Self::high_as_ref() instead.

impl<T: Float> Interval<T>

pub fn low_f(&self) -> T

Get the lower bound of the interval (if any) for floating point types. This function returns the negative infinite value for T for lower one-sided intervals.

pub fn high_f(&self) -> T

Get the upper bound of the interval (if any) for floating point types. This function returns the infinite value for T for upper one-sided intervals.

pub fn relative_to(&self, reference: &Interval<T>) -> Interval<T>

Given two intervals, compute the relative interval compared to the reference (argument). The relative interval is defined as the interval of the ratios of the two intervals.

E.g., for two two-sided intervals \( [x, y] \) and reference \( [a, b] \), the relative interval is \( [(x-b)/b, (y-a)/a] \).

impl<T: PrimInt + Signed> Interval<T>

pub fn low_i(&self) -> T

Get the lower bound of the interval (if any) for signed integer types. This function returns the minimal value for T for lower one-sided intervals.

pub fn high_i(&self) -> T

Get the upper bound of the interval (if any) for signed integer types. This function returns the maximal value for T for upper one-sided intervals.

impl<T: PrimInt + Unsigned> Interval<T>

pub fn low_u(&self) -> T

Get the lower bound of the interval (if any) for unsigned integer types. This function returns 0 for lower one-sided intervals.

pub fn high_u(&self) -> T

Get the upper bound of the interval (if any) for unsigned integer types. This function returns the maximum value for T for upper one-sided intervals.

impl<T: PartialOrd> Interval<T>

pub fn low_as_ref(&self) -> Option<&T>

Get a reference to the lower bound of the interval (if any).

See also Self::low() if cloning is not an issue.

pub fn high_as_ref(&self) -> Option<&T>

Get a reference to the upper bound of the interval (if any).

See also Self::high() if cloning is not an issue.

impl<T: PartialOrd + Sub<Output = T> + Zero + Clone> Interval<T>

pub fn width(&self) -> Option<T>

Compute the width of the interval. If the interval is one-sided, the function returns None.

Trait Implementations

impl<T: AbsDiffEq + PartialOrd> AbsDiffEq for Interval<T>

where T::Epsilon: Copy,

Available on crate feature approx only.

type Epsilon = <T as AbsDiffEq>::Epsilon

Used for specifying relative comparisons.

fn default_epsilon() -> T::Epsilon

The default tolerance to use when testing values that are close together.

fn abs_diff_eq(&self, other: &Self, epsilon: T::Epsilon) -> bool

A test for equality that uses the absolute difference to compute the approximate equality of two numbers.

fn abs_diff_ne(&self, other: &Rhs, epsilon: Self::Epsilon) -> bool

The inverse of AbsDiffEq::abs_diff_eq.

impl<F: Add<F, Output = F> + PartialOrd + Copy> Add<F> for Interval<F>

type Output = Interval<F>

The resulting type after applying the + operator.

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

Performs the + operation.

impl<F: Num + PartialOrd + Copy> Add for Interval<F>

type Output = Interval<F>

The resulting type after applying the + operator.

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

Performs the + operation.

impl<T: PartialOrd> AsRef<Interval<T>> for Interval<T>

fn as_ref(&self) -> &Self

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

impl<T: PartialOrd + Clone> Clone for Interval<T>

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Interval<T>

where T: PartialOrd + Debug,

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

Formats the value using the given formatter.

impl<T: PartialOrd + Display> Display for Interval<T>

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

Formats the value using the given formatter.

impl<F: Div<F, Output = F> + PartialOrd + Copy> Div<F> for Interval<F>

type Output = Interval<F>

The resulting type after applying the / operator.

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

Performs the / operation.

impl<T: PartialOrd + Clone> From<Interval<T>> for (Option<T>, Option<T>)

fn from(interval: Interval<T>) -> Self

Convert an interval to a tuple of optional bounds. The first element of the tuple is the lower bound, the second element is the upper bound. If the interval is one-sided, one of the bounds is None,

impl From<Interval<f32>> for (f32, f32)

fn from(value: Interval<f32>) -> Self

Converts to this type from the input type.

impl From<Interval<f64>> for (f64, f64)

fn from(value: Interval<f64>) -> Self

Converts to this type from the input type.

impl From<Interval<i128>> for (i128, i128)

fn from(value: Interval<i128>) -> Self

Converts to this type from the input type.

impl From<Interval<i16>> for (i16, i16)

fn from(value: Interval<i16>) -> Self

Converts to this type from the input type.

impl From<Interval<i32>> for (i32, i32)

fn from(value: Interval<i32>) -> Self

Converts to this type from the input type.

impl From<Interval<i64>> for (i64, i64)

fn from(value: Interval<i64>) -> Self

Converts to this type from the input type.

impl From<Interval<i8>> for (i8, i8)

fn from(value: Interval<i8>) -> Self

Converts to this type from the input type.

impl From<Interval<isize>> for (isize, isize)

fn from(value: Interval<isize>) -> Self

Converts to this type from the input type.

impl From<Interval<u128>> for (u128, u128)

fn from(value: Interval<u128>) -> Self

Converts to this type from the input type.

impl From<Interval<u16>> for (u16, u16)

fn from(value: Interval<u16>) -> Self

Converts to this type from the input type.

impl From<Interval<u32>> for (u32, u32)

fn from(value: Interval<u32>) -> Self

Converts to this type from the input type.

impl From<Interval<u64>> for (u64, u64)

fn from(value: Interval<u64>) -> Self

Converts to this type from the input type.

impl From<Interval<u8>> for (u8, u8)

fn from(value: Interval<u8>) -> Self

Converts to this type from the input type.

impl From<Interval<usize>> for (usize, usize)

fn from(value: Interval<usize>) -> Self

Converts to this type from the input type.

impl<T: PartialOrd> From<RangeFrom<T>> for Interval<T>

fn from(range: RangeFrom<T>) -> Self

Create an upper one-sided interval from a range starting from a given value.

use stats_ci::Interval;
use std::ops::RangeFrom;
let interval = Interval::from(1..);
assert_eq!(interval, Interval::new_upper(1));

impl<T: PartialOrd> From<RangeToInclusive<T>> for Interval<T>

fn from(range: RangeToInclusive<T>) -> Self

Create a lower one-sided interval from a range ending at a given value.

use stats_ci::Interval;
use std::ops::RangeToInclusive;
let interval = Interval::from(..=1);
assert_eq!(interval, Interval::new_lower(1));

impl<T: PartialOrd + Hash> Hash for Interval<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<F: Mul<F, Output = F> + PartialOrd + Copy> Mul<F> for Interval<F>

type Output = Interval<F>

The resulting type after applying the * operator.

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

Performs the * operation.

impl<F: Neg<Output = F> + PartialOrd + Copy> Neg for Interval<F>

type Output = Interval<F>

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl<T> PartialEq for Interval<T>

where T: PartialOrd + PartialEq,

fn eq(&self, other: &Interval<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 Interval<T>

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

Compare two intervals. Given two intervals a and b, a < b if and only if the upper bound of a is less than the lower bound of b. Although interval bounds are inclusive, two intervals that overlap only at a single bound are considered ordered. E.g., intervals [x,y] is considered less than [a,b] if y==a and x<b.

Examples

let a = Interval::new(0, 10)?;
let b = Interval::new(10, 20)?;
let c = Interval::new(11, 20)?;
let d = Interval::new(0, 10)?;
let e = Interval::new_upper(10);
assert_eq!(a.partial_cmp(&b), Some(Ordering::Less));
assert_eq!(a.partial_cmp(&c), Some(Ordering::Less));
assert_eq!(a.partial_cmp(&d), Some(Ordering::Equal));
assert_eq!(a.partial_cmp(&e), Some(Ordering::Less));
assert_eq!(c.partial_cmp(&a), Some(Ordering::Greater));
assert_eq!(b.partial_cmp(&c), None);

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: PartialOrd> RangeBounds<T> for Interval<T>

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

Start index bound.

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

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<T: RelativeEq + PartialOrd> RelativeEq for Interval<T>

where T::Epsilon: Copy,

Available on crate feature approx only.

fn default_max_relative() -> T::Epsilon

The default relative tolerance for testing values that are far-apart.

fn relative_eq( &self, other: &Self, epsilon: T::Epsilon, max_relative: T::Epsilon, ) -> bool

A test for equality that uses a relative comparison if the values are far apart.

fn relative_ne( &self, other: &Rhs, epsilon: Self::Epsilon, max_relative: Self::Epsilon, ) -> bool

The inverse of RelativeEq::relative_eq.

impl<F: Sub<F, Output = F> + PartialOrd + Copy> Sub<F> for Interval<F>

type Output = Interval<F>

The resulting type after applying the - operator.

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

Performs the - operation.

impl<F: Num + PartialOrd + Copy> Sub for Interval<F>

type Output = Interval<F>

The resulting type after applying the - operator.

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

Performs the - operation.

impl<T: PartialOrd> TryFrom<(Option<T>, Option<T>)> for Interval<T>

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

Create a new interval from a tuple of optional bounds. The first element of the tuple is the lower bound, the second element is the upper bound. If one of the bounds is None, the interval is one-sided. If both bounds are None, an error is returned.

type Error = IntervalError

The type returned in the event of a conversion error.

impl<T: PartialOrd> TryFrom<(T, T)> for Interval<T>

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

Create a new interval from a tuple of bounds. The first element of the tuple is the lower bound, the second element is the upper bound. If the lower bound is greater than the upper bound, an error is returned.

type Error = IntervalError

The type returned in the event of a conversion error.

impl<T: PartialOrd> TryFrom<RangeInclusive<T>> for Interval<T>

fn try_from(range: RangeInclusive<T>) -> Result<Self, Self::Error>

Create an interval from an inclusive range. The range must be non-empty or the function will return an error.

use stats_ci::Interval;
use std::ops::RangeInclusive;
let interval = Interval::try_from(1..=2);
assert!(interval.is_ok());
assert_eq!(interval.unwrap(), Interval::new(1, 2).unwrap());

type Error = IntervalError

The type returned in the event of a conversion error.

impl<T: UlpsEq + PartialOrd> UlpsEq for Interval<T>

where T::Epsilon: Copy,

Available on crate feature approx only.

fn default_max_ulps() -> u32

The default ULPs to tolerate when testing values that are far-apart.

fn ulps_eq(&self, other: &Self, epsilon: T::Epsilon, max_ulps: u32) -> bool

A test for equality that uses units in the last place (ULP) if the values are far apart.

fn ulps_ne(&self, other: &Rhs, epsilon: Self::Epsilon, max_ulps: u32) -> bool

The inverse of UlpsEq::ulps_eq.

impl<T: PartialOrd + Copy> Copy for Interval<T>

impl<T> StructuralPartialEq for Interval<T>

where T: PartialOrd,