Enum infinitable::Infinitable

pub enum Infinitable<T> {
    Finite(T),
    Infinity,
    NegativeInfinity,
}

An “infinitable” value, one that can be either finite or infinite

Versioning

Available since 1.0.0. Variants are re-exported since 1.3.0.

Variants

Finite(T)

A finite value T

Infinity

Positive infinity, which compares greater than all other values

NegativeInfinity

Negative infinity, which compares less than all other values

Implementations

impl<T> Infinitable<T>

pub fn is_finite(&self) -> bool

Returns true if the value is Finite.

Examples

use infinitable::*;

let finite = Finite(5);
assert!(finite.is_finite());
let infinite: Infinitable<i32> = Infinity;
assert!(!infinite.is_finite());

Versioning

Available since 1.0.0.

pub fn finite(self) -> Option<T>

Converts from an Infinitable<T> to an Option<T>.

Converts self into an Option<T> possibly containing a finite value, consuming self.

Examples

use infinitable::*;

let finite = Finite(5);
assert_eq!(Some(5), finite.finite());
let infinite: Infinitable<i32> = Infinity;
assert_eq!(None, infinite.finite());

Versioning

Available since 1.1.0.

pub fn finite_or_infinity(option: Option<T>) -> Infinitable<T>

Converts from Option<T> to Finite or Infinity.

Some(T) is converted to Finite(T), and None is converted to Infinity.

Examples

use infinitable::*;

let finite = Finite(5);
assert_eq!(finite, Infinitable::finite_or_infinity(Some(5)));
let infinite: Infinitable<i32> = Infinity;
assert_eq!(infinite, Infinitable::finite_or_infinity(None));

Versioning

Available since 1.3.0.

pub fn finite_or_negative_infinity(option: Option<T>) -> Infinitable<T>

Converts from Option<T> to Finite or NegativeInfinity.

Some(T) is converted to Finite(T), and None is converted to NegativeInfinity.

Examples

use infinitable::*;

let finite = Finite(5);
assert_eq!(finite, Infinitable::finite_or_negative_infinity(Some(5)));
let infinite: Infinitable<i32> = NegativeInfinity;
assert_eq!(infinite, Infinitable::finite_or_negative_infinity(None));

Versioning

Available since 1.3.0.

pub fn convert_into<U>(self) -> Infinitable<U>

where T: Into<U>,

Converts the value into a different type, based on the conversion of the underlying type T.

Infinite values are preserved as is, while finite values are converted using into on the underlying value.

Examples

use infinitable::*;
let finite = Finite(5);
let finite64: Infinitable<i64> = finite.convert_into();
assert_eq!(Finite(5i64), finite64);
let infinite: Infinitable<i32> = Infinity;
let infinite64: Infinitable<i64> = infinite.convert_into();
assert_eq!(Infinity, infinite64);

Versioning

Available since 1.6.0.

pub fn try_convert_into<U>(self) -> Result<Infinitable<U>, T::Error>

where T: TryInto<U>,

Converts the value into a different type, based on the conversion of the underlying type T.

Infinite values are preserved as is, while finite values are converted using try_into on the underlying value. Conversion of infinite values always succeeds, while conversion of finite values may fail.

Examples

use infinitable::*;
use std::num::TryFromIntError;
let finite = Finite(1000);
let finite8: Result<Infinitable<i8>, TryFromIntError>
    = finite.try_convert_into();
assert!(finite8.is_err());
let infinite: Infinitable<i32> = Infinity;
let infinite8: Result<Infinitable<i8>, TryFromIntError>
    = infinite.try_convert_into();
assert_eq!(Ok(Infinity), infinite8);

Versioning

Available since 1.6.0.

Trait Implementations

impl<T> Add for Infinitable<T>

where T: Add,

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

Adds two values.

The addition operation follows these rules:

self	rhs	result
Finite	Finite	Finite (add values)
Finite	Infinity	Infinity
Finite	NegativeInfinity	NegativeInfinity
Infinity	Finite	Infinity
Infinity	Infinity	Infinity
Infinity	NegativeInfinity	Undefined (panic)
NegativeInfinity	Finite	NegativeInfinity
NegativeInfinity	Infinity	Undefined (panic)
NegativeInfinity	NegativeInfinity	NegativeInfinity

Examples

use infinitable::*;

assert_eq!(Finite(5), Finite(2) + Finite(3));
assert_eq!(Infinity, Finite(1) + Infinity);
assert_eq!(NegativeInfinity, NegativeInfinity + Finite(1));

The addition operation panics with Infinity and NegativeInfinity:

use infinitable::*;

let infinity: Infinitable<i32> = Infinity;
let negative_infinity: Infinitable<i32> = NegativeInfinity;
let _ = infinity + negative_infinity;

Panics

Panics if the operands consist of Infinity and NegativeInfinity.

Versioning

Available since 1.5.0.

type Output = Infinitable<<T as Add>::Output>

The resulting type after applying the + operator.

impl<T: Clone> Clone for Infinitable<T>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: Debug> Debug for Infinitable<T>

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

Formats the value using the given formatter.

impl<T> Display for Infinitable<T>

where T: Display,

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

Formats the value, when the underlying type T supports formatting.

Infinity is formatted to "inf", NegativeInfinity is formatted to "-inf", and Finite is formatted based on the underlying value.

Examples

use infinitable::*;

let finite = Finite(5);
assert_eq!("5", format!("{}", finite));
let infinity: Infinitable<i32> = Infinity;
assert_eq!("inf", format!("{}", infinity));
let negative_infinity: Infinitable<i32> = NegativeInfinity;
assert_eq!("-inf", format!("{}", negative_infinity));

Versioning

Available since 1.2.0.

impl<T> Div for Infinitable<T>

where T: Div + Zero + PartialOrd, <T as Div>::Output: Zero,

fn div(self, rhs: Infinitable<T>) -> Infinitable<<T as Div>::Output>

Divides two values.

The division operation follows these rules:

self	rhs	result
Finite (> 0)	Finite (~ 0)	Infinity
Finite (~ 0)	Finite (~ 0)	Undefined (panic)
Finite (< 0)	Finite (~ 0)	NegativeInfinity
Finite	Finite (<> 0)	Finite (divide values)
Finite	Infinity	Zero
Finite	NegativeInfinity	Zero
Infinity	Finite (> 0)	Infinity
Infinity	Finite (~ 0)	Infinity
Infinity	Finite (< 0)	NegativeInfinity
Infinity	Infinity	Undefined (panic)
Infinity	NegativeInfinity	Undefined (panic)
NegativeInfinity	Finite (> 0)	NegativeInfinity
NegativeInfinity	Finite (~ 0)	NegativeInfinity
NegativeInfinity	Finite (< 0)	Infinity
NegativeInfinity	Infinity	Undefined (panic)
NegativeInfinity	NegativeInfinity	Undefined (panic)

(In the table, “~ 0” refers to a value that is either equal to or unordered with zero, and “<> 0” refers to a value that is either greater than or less than zero.)

Examples

use infinitable::*;

assert_eq!(Finite(3), Finite(6) / Finite(2));
assert_eq!(Infinity, Infinity / Finite(1));
assert_eq!(Infinity, NegativeInfinity / Finite(-2));
assert_eq!(NegativeInfinity, NegativeInfinity / Finite(1));
assert_eq!(NegativeInfinity, Infinity / Finite(-2));
assert_eq!(Finite(0), Finite(1) / Infinity);
assert_eq!(Finite(0), Finite(1) / NegativeInfinity);

The division operation panics when an infinite value is divided by another infinite value, or when zero is divided by itself:

use infinitable::*;

let infinity: Infinitable<i32> = Infinity;
let _ = infinity / infinity;

use infinitable::*;

let _ = Finite(0) / Finite(0);

Panics

Panics if both operands are either Infinity or NegativeInfinity, or both operands are Finite with an underlying value equal to or unordered with zero.

Versioning

Available since 1.5.0.

type Output = Infinitable<<T as Div>::Output>

The resulting type after applying the / operator.

impl<T> From<T> for Infinitable<T>

fn from(value: T) -> Infinitable<T>

Converts from a value T to Finite containing the underlying value.

Note that there is no special handling for pre-existing infinite values. Consider using from_f32 or from_f64 for floating-point numbers.

Examples

use infinitable::*;

let finite = Infinitable::from(5);
assert_eq!(Finite(5), finite);

// Warning: There is no special handling for pre-existing infinite values
let fp_infinity = Infinitable::from(f32::INFINITY);
assert_eq!(Finite(f32::INFINITY), fp_infinity);
assert_ne!(Infinity, fp_infinity);

Versioning

Available since 1.2.0.

impl<T: Hash> Hash for Infinitable<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 for Infinitable<T>

where T: Mul + Zero + PartialOrd,

fn mul(self, rhs: Infinitable<T>) -> Infinitable<<T as Mul>::Output>

Multiplies two values.

The multiplication operation follows these rules:

self	rhs	result
Finite	Finite	Finite (multiply values)
Finite (> 0)	Infinity	Infinity
Finite (~ 0)	Infinity	Undefined (panic)
Finite (< 0)	Infinity	NegativeInfinity
Finite (> 0)	NegativeInfinity	NegativeInfinity
Finite (~ 0)	NegativeInfinity	Undefined (panic)
Finite (< 0)	NegativeInfinity	Infinity
Infinity	Finite (> 0)	Infinity
Infinity	Finite (~ 0)	Undefined (panic)
Infinity	Finite (< 0)	NegativeInfinity
Infinity	Infinity	Infinity
Infinity	NegativeInfinity	NegativeInfinity
NegativeInfinity	Finite (> 0)	NegativeInfinity
NegativeInfinity	Finite (~ 0)	Undefined (panic)
NegativeInfinity	Finite (< 0)	Infinity
NegativeInfinity	Infinity	NegativeInfinity
NegativeInfinity	NegativeInfinity	Infinity

(In the table, “~ 0” refers to a value that is either equal to or unordered with zero.)

Examples

use infinitable::*;

assert_eq!(Finite(6), Finite(2) * Finite(3));
assert_eq!(Infinity, Infinity * Finite(2));
assert_eq!(Infinity, Finite(-1) * NegativeInfinity);
assert_eq!(NegativeInfinity, NegativeInfinity * Finite(2));
assert_eq!(NegativeInfinity, Finite(-1) * Infinity);

The multiplication operation panics when an infinite value is multiplied with zero:

use infinitable::*;

let infinity: Infinitable<i32> = Infinity;
let _ = infinity * Finite(0);

Panics

Panics if one of the operands is Infinity or NegativeInfinity and the other is a Finite value with an underlying value equal to or unordered with zero.

Versioning

Available since 1.5.0.

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

The resulting type after applying the * operator.

impl<T> Neg for Infinitable<T>

where T: Neg,

fn neg(self) -> Infinitable<T::Output>

Negates the value, when the underlying type T supports negation.

Infinity is negated to NegativeInfinity (and vice versa), and Finite is negated based on the underlying value.

Examples

use infinitable::*;

let finite = Finite(5);
assert_eq!(Finite(-5), -finite);
let infinity: Infinitable<i32> = Infinity;
assert_eq!(NegativeInfinity, -infinity);
let negative_infinity: Infinitable<i32> = NegativeInfinity;
assert_eq!(Infinity, -negative_infinity);

Versioning

Available since 1.3.0.

type Output = Infinitable<<T as Neg>::Output>

The resulting type after applying the - operator.

impl<T> Ord for Infinitable<T>

where T: Ord,

Total order, when the underlying type T implements a total order.

NegativeInfinity compares less than all other values, and Infinity compares greater than all other values.

Examples

use infinitable::*;
use std::cmp::Ordering;

let finite = Finite(5);
let infinity = Infinity;
let negative_infinity = NegativeInfinity;

assert_eq!(Ordering::Less, finite.cmp(&infinity));
assert_eq!(Ordering::Greater, finite.cmp(&negative_infinity));

Versioning

Available since 1.0.0.

fn cmp(&self, other: &Self) -> 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 + PartialOrd,

Restrict a value to a certain interval.

impl<T: PartialEq> PartialEq for Infinitable<T>

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

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

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> PartialOrd for Infinitable<T>

where T: PartialOrd,

Partial order, when the underlying type T implements a partial order.

NegativeInfinity compares less than all other values, and Infinity compares greater than all other values.

Examples

use infinitable::*;
use std::cmp::Ordering;

let finite = Finite(5);
let infinity = Infinity;
let negative_infinity = NegativeInfinity;

assert_eq!(Some(Ordering::Less), finite.partial_cmp(&infinity));
assert_eq!(Some(Ordering::Greater), finite.partial_cmp(&negative_infinity));

Versioning

Available since 1.0.0.

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

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

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

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

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

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

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

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

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

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

impl<T> Sub for Infinitable<T>

where T: Sub,

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

Subtracts two values.

The subtraction operation follows these rules:

self	rhs	result
Finite	Finite	Finite (subtract values)
Finite	Infinity	NegativeInfinity
Finite	NegativeInfinity	Infinity
Infinity	Finite	Infinity
Infinity	Infinity	Undefined (panic)
Infinity	NegativeInfinity	Infinity
NegativeInfinity	Finite	NegativeInfinity
NegativeInfinity	Infinity	NegativeInfinity
NegativeInfinity	NegativeInfinity	Undefined (panic)

Examples

use infinitable::*;

assert_eq!(Finite(3), Finite(5) - Finite(2));
assert_eq!(Infinity, Infinity - Finite(1));
assert_eq!(Infinity, Finite(1) - NegativeInfinity);
assert_eq!(NegativeInfinity, NegativeInfinity - Finite(1));
assert_eq!(NegativeInfinity, Finite(1) - Infinity);

The subraction operation panics when an infinite value is subtracted from itself:

use infinitable::*;

let infinity: Infinitable<i32> = Infinity;
let _ = infinity - infinity;

Panics

Panics if the operands are both Infinity or both NegativeInfinity.

Versioning

Available since 1.5.0.

type Output = Infinitable<<T as Sub>::Output>

The resulting type after applying the - operator.

impl<T: Copy> Copy for Infinitable<T>

impl<T: Eq> Eq for Infinitable<T>

impl<T> StructuralPartialEq for Infinitable<T>