Struct Finite 

pub struct Finite<T: FiniteFloat>(/* private fields */);

Experimental: A transparent wrapper around f64 and friends with total ordering.

Comparison, equality, and hashing all agree with total_cmp after zero normalization.

Basic Usage

use range_set_blaze::{RangeSetBlaze, FiniteF64, FiniteF32};
let set = RangeSetBlaze::from_iter([FiniteF64::new(3.0)..=FiniteF64::new(5.0)]);
assert!(set.contains(FiniteF64::new(3.1)));
assert!(!set.contains(FiniteF64::new(2.9)));

let set = RangeSetBlaze::from(FiniteF64::from_primitive_range(3.0..=5.0));
assert!(set.contains(FiniteF64::new(4.9)));
assert!(!set.contains(FiniteF64::new(5.1)));

let set = RangeSetBlaze::from_iter(FiniteF32::from_primitive_ranges([3.0..=5.0, 7.0..=9.0]));
assert!(set.contains(FiniteF32::new(4.0)));
assert!(!set.contains(FiniteF32::new(6.0)));

Enabling

This type is experimental and must be enabled with the float_experimental feature.

cargo add range-set-blaze --features "float_experimental"

That provides the FiniteF32 and FiniteF64 types.

If you’re building with nightly, you can instead use the float_nightly_experimental feature.

cargo add range-set-blaze --features "float_nightly_experimental"

To also use the FiniteF16 and FiniteF128 types.

Implementations

impl<T: FiniteFloat> Finite<T>

pub const MIN: Self

The minimum value that can be represented by the type.
Maps directly to crate::Integer::min_value()

Examples

use range_set_blaze::FiniteF64;

assert_eq!(FiniteF64::MIN, FiniteF64::new(f64::MIN));

pub const MAX: Self

The maximum value that can be represented by the type.
Maps directly to crate::Integer::max_value()

Examples

use range_set_blaze::FiniteF64;

assert_eq!(FiniteF64::MAX, FiniteF64::new(f64::MAX));

pub const MAX_SIZE: T::SafeLen = T::MAX_SIZE

The maximum possible size of a range, i.e. the size if [MIN..=MAX] For Finite types, this is unusual because NaN and infinity values are excluded, and -0.0 and +0.0 share one slot after normalization.

Examples

use range_set_blaze::FiniteF32;

assert_eq!(FiniteF32::MAX_SIZE, 0xFF00_0000_u32 - 1);

pub fn new(x: T) -> Self

Creates a new Finite from a primitive float. Only finite values are legal

Examples

use range_set_blaze::FiniteF64;

let _ = FiniteF64::new(1.0);

Panics

Panics if x.is_finite() returns false

pub fn try_new(x: T) -> Option<Self>

Creates a new Finite from a primitive float.

Returns None if the float is not finite (NaN or infinity).

Examples

use range_set_blaze::FiniteF64;

assert_eq!(FiniteF64::try_new(1.0), Some(FiniteF64::new(1.0)));
assert_eq!(FiniteF64::try_new(f64::NAN), None);

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

Creates a new Finite from a primitive float without validating it.

This is the unchecked building block every validating constructor in this module (new, try_new, from_primitive_range, values, from_primitive_slice, …) is defined in terms of. Prefer those; only reach for this when you have already independently established the safety precondition below and need to skip the redundant check.

Safety

The caller must guarantee that:

• x is finite: not NaN, not +/-infinity.
• x is not -0.0: zero must already be canonicalized to +0.0.

Finite has a public type invariant (“only finite values, with zero canonicalized to +0.0, are legal”). Even though today’s implementation would only produce incorrect results (wrong MAX_SIZE, a duplicated zero slot, after/before landing somewhere unexpected) rather than immediate undefined behavior if this precondition is violated, safe code must never be able to construct a value that breaks it. This preserves the option for this crate, and downstream code, to rely on the invariant in future (potentially unsafe) abstractions without an audit of every safe caller.

pub fn inclusive_end_from_start(self, b: T::SafeLen) -> Self

Computes self + (b - 1) where b is of type SafeLen.

Panics

Panics if b is not small enough that the result stays within range for T (checked unconditionally, in both debug and release builds, so safe code can never construct a Finite value that breaks its invariant this way).

pub fn start_from_inclusive_end(self, b: T::SafeLen) -> Self

Computes self - (b - 1) where b is of type SafeLen.

Panics

Panics if b is not small enough that the result stays within range for T (checked unconditionally, in both debug and release builds, so safe code can never construct a Finite value that breaks its invariant this way).

pub const fn into_inner(self) -> T

Returns the wrapped value.

Examples

use range_set_blaze::FiniteF64;

assert_eq!(FiniteF64::new(42.0).into_inner(), 42.0);

pub fn after(self) -> Self

Returns the next float, in total order.

Examples

use range_set_blaze::FiniteF64;

assert_eq!(FiniteF64::new(42.0).after().before().into_inner(), 42.0);

Panics

Panics if self is the maximum value (checked unconditionally, in both debug and release builds, so safe code can never construct a Finite value that breaks its invariant this way).

pub fn before(self) -> Self

Returns the previous float, in total order.

Examples

use range_set_blaze::FiniteF64;

assert_eq!(FiniteF64::new(42.0).before().after().into_inner(), 42.0);

Panics

Panics if self is the minimum value (checked unconditionally, in both debug and release builds, so safe code can never construct a Finite value that breaks its invariant this way).

pub fn checked_after(self) -> Option<Self>

Returns the next float, in total order.

Returns None if self is the maximum value.

Examples

use range_set_blaze::FiniteF64;

let value = FiniteF64::new(42.0);
assert_eq!(value.checked_after(), Some(value.after()));
let value = FiniteF64::MAX;
assert_eq!(value.checked_after(), None);

pub fn checked_before(self) -> Option<Self>

Returns the previous float, in total order.

Returns None if self is the minimum value.

Examples

use range_set_blaze::FiniteF64;

let value = FiniteF64::new(42.0);
assert_eq!(value.checked_before(), Some(value.before()));
let value = FiniteF64::MIN;
assert_eq!(value.checked_before(), None);

pub fn from_primitive_range(range: RangeInclusive<T>) -> RangeInclusive<Self>

Converts an inclusive primitive range into an inclusive Finite range.

“Primitive” here means Rust’s built-in float type (e.g. f64).

Examples

use range_set_blaze::{RangeSetBlaze, FiniteF64};

let short = RangeSetBlaze::from(FiniteF64::from_primitive_range(3.0..=5.0));
let long = RangeSetBlaze::from(FiniteF64::new(3.0)..=FiniteF64::new(5.0));
assert_eq!(short, long);

Panics

Panics if start or end is not finite.

pub fn from_primitive_ranges<I>( ranges: I, ) -> impl Iterator<Item = RangeInclusive<Self>>

where I: IntoIterator<Item = RangeInclusive<T>>,

Converts inclusive primitive ranges into inclusive Finite ranges.

“Primitive” here means Rust’s built-in float type (e.g. f64).

Examples

use range_set_blaze::{RangeSetBlaze, FiniteF64};

let short = RangeSetBlaze::from_iter(FiniteF64::from_primitive_ranges([1.0..=2.0, 3.0..=4.0]));
let long = RangeSetBlaze::from_iter([FiniteF64::new(1.0)..=FiniteF64::new(2.0), FiniteF64::new(3.0)..=FiniteF64::new(4.0)]);
assert_eq!(short, long);

Panics

Panics when the returned iterator is consumed if any range endpoint is not finite.

pub fn values<I>(values: I) -> impl Iterator<Item = Self>

where I: IntoIterator<Item = T>,

Convenience method to convert primitive values into ordered Finite values.

Examples

use range_set_blaze::{RangeSetBlaze, FiniteF64};

let short = RangeSetBlaze::from_iter(FiniteF64::values([1.0, 2.0, 3.0, 4.0]));
let long = RangeSetBlaze::from_iter([FiniteF64::new(1.0), FiniteF64::new(2.0), FiniteF64::new(3.0), FiniteF64::new(4.0)]);
assert_eq!(short, long);

Panics

Panics (when iterated) if any value is not finite.

pub fn from_primitive_slice(values: &[T]) -> &[Self]

Views primitive values as ordered Finite values, validating as it goes.

“Primitive” here means Rust’s built-in float type (e.g. f64).

This runs in O(n) (to validate every element) and does not allocate.

Examples

use range_set_blaze::{RangeSetBlaze, FiniteF64};

let short = RangeSetBlaze::from_iter(FiniteF64::from_primitive_slice(&[1.0, 2.0, 3.0, 4.0]));
let long = RangeSetBlaze::from_iter([FiniteF64::new(1.0), FiniteF64::new(2.0), FiniteF64::new(3.0), FiniteF64::new(4.0)]);
assert_eq!(short, long);

Panics

Panics if any element is not finite, or is -0.0 (which can’t be normalized to +0.0 without copying — see Finite::from_primitive_slice_unchecked if you need a true zero-copy view and can guarantee your data already satisfies Finite’s invariant).

pub const unsafe fn from_primitive_slice_unchecked(values: &[T]) -> &[Self]

Views primitive values as ordered Finite values, without validating them.

“Primitive” here means Rust’s built-in float type (e.g. f64).

This runs in O(1) and does not allocate.

Safety

The caller must guarantee that every element of values is finite (not NaN, not +/-infinity) and not -0.0 (zero must already be canonicalized to +0.0). Because the returned slice is a live view over the same memory (not a copy), there is no opportunity to normalize -0.0 even if the caller wanted to; the data must already be clean.

Finite has a public type invariant that safe code must never be able to break, even though violating it today would only produce incorrect results (see Finite::new_unchecked for the full rationale).

Trait Implementations

impl<T: Clone + FiniteFloat> Clone for Finite<T>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Copy + FiniteFloat> Copy for Finite<T>

impl<T: Debug + FiniteFloat> Debug for Finite<T>

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

Formats the value using the given formatter.

impl<T: Default + FiniteFloat> Default for Finite<T>

fn default() -> Finite<T>

Returns the “default value” for a type.

impl<T: FiniteFloat> Eq for Finite<T>

impl<T: FiniteFloat> Hash for Finite<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: FiniteFloat> Integer for Finite<T>

type SafeLen = <T as FiniteFloat>::SafeLen

The type representing the safe length for a RangeSetBlaze. For example, the length of a RangeSetBlaze<u8> is u16 to handle ranges up to 256 elements. For larger types like u128, this is represented by a custom type UIntPlusOne<u128>.

fn checked_add_one(self) -> Option<Self>

Attempts to add one to the current value, returning None if the operation would overflow.

fn add_one(self) -> Self

Adds one to the current value, panicking in debug mode if the operation overflows.

fn sub_one(self) -> Self

Subtracts one from the current value, panicking in debug mode if the operation underflows.

fn assign_sub_one(&mut self)

Subtracts one from the current value and assigns it back to self.

fn range_next(range: &mut RangeInclusive<Self>) -> Option<Self>

Advances the iterator for the given range by one step, returning the next value or None if the range is exhausted.

fn range_next_back(range: &mut RangeInclusive<Self>) -> Option<Self>

Advances the iterator for the given range in reverse by one step, returning the previous value or None if the range is exhausted.

fn min_value() -> Self

Returns the minimum value that can be represented by the type.

fn max_value() -> Self

Returns the maximum value that can be represented by the type.

fn from_slice(slice: impl AsRef<[Self]>) -> RangeSetBlaze<Self>

Creates a RangeSetBlaze from a slice, specific to the integer type.

fn safe_len(r: &RangeInclusive<Self>) -> Self::SafeLen

Calculates the length of a range without overflow.

fn safe_len_to_f64_lossy(len: Self::SafeLen) -> f64

Converts Integer::SafeLen to f64, potentially losing precision for large values.

fn f64_to_safe_len_lossy(f: f64) -> Self::SafeLen

Converts a f64 to Integer::SafeLen using the formula f as Self::SafeLen. For large integer types, this will result in a loss of precision.

fn inclusive_end_from_start(self, b: Self::SafeLen) -> Self

Computes self + (b - 1) where b is of type Integer::SafeLen.

fn start_from_inclusive_end(self, b: Self::SafeLen) -> Self

Computes self - (b - 1) where b is of type Integer::SafeLen.

fn exhausted_range() -> RangeInclusive<Self>

Returns an exhausted range, which is a range that starts from the maximum value and ends at the minimum value. This results in an empty range.

impl<T: FiniteFloat> Ord for Finite<T>

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,

Restrict a value to a certain interval.

impl<T: FiniteFloat> PartialEq for Finite<T>

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

Equality operator ==.

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

Inequality operator !=.

impl<T: FiniteFloat> PartialOrd for Finite<T>

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

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.