Struct NotNan 

pub struct NotNan<T: NotNanFloat>(/* private fields */);

A transparent wrapper around f64 and friends with total ordering.

Comparison, equality, and hashing all agree with total_cmp after zero normalization. Every value except NaN is legal, including +infinity and -infinity.

Basic Usage

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

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

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

The Full Non-NaN Domain

The primitive -∞..=+∞ range converts to NotNanF64::MIN..=NotNanF64::MAX, the complete ordered domain of legal values: every non-NaN f64, including both infinities, is in the range.

use range_set_blaze::{NotNanF64, RangeSetBlaze};

assert_eq!(NotNanF64::MIN, NotNanF64::new(f64::NEG_INFINITY));
assert_eq!(NotNanF64::MAX, NotNanF64::new(f64::INFINITY));

let primitive_domain =
    NotNanF64::from_primitive_range(f64::NEG_INFINITY..=f64::INFINITY);
let full_domain = NotNanF64::MIN..=NotNanF64::MAX;
assert_eq!(primitive_domain, full_domain);

let full_domain = RangeSetBlaze::from(full_domain);
assert!(full_domain.contains(NotNanF64::new(f64::NEG_INFINITY)));
assert!(full_domain.contains(NotNanF64::new(-42.0)));
assert!(full_domain.contains(NotNanF64::new(0.0)));
assert!(full_domain.contains(NotNanF64::new(42.0)));
assert!(full_domain.contains(NotNanF64::new(f64::INFINITY)));

The stable NotNanF32 and NotNanF64 types are available by default. On nightly, enable float_nightly_experimental to also use the NotNanF16 and NotNanF128 types.

Implementations

impl<T: NotNanFloat> NotNan<T>

pub const MIN: Self

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

Examples

use range_set_blaze::NotNanF64;

assert_eq!(NotNanF64::MIN, NotNanF64::new(f64::NEG_INFINITY));

pub const MAX: Self

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

Examples

use range_set_blaze::NotNanF64;

assert_eq!(NotNanF64::MAX, NotNanF64::new(f64::INFINITY));

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

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

Examples

use range_set_blaze::NotNanF32;

assert_eq!(NotNanF32::MAX_SIZE, 0xFF00_0000_u32 + 1);

pub fn new(x: T) -> Self

Creates a new NotNan from a primitive float. Any value except NaN is legal, including the infinities.

Examples

use range_set_blaze::NotNanF64;

let _ = NotNanF64::new(1.0);
let _ = NotNanF64::new(f64::INFINITY);

Panics

Panics if x is NaN.

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

Creates a new NotNan from a primitive float.

Returns None if the float is NaN.

Examples

use range_set_blaze::NotNanF64;

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

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

Creates a new NotNan 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 not NaN.
• x is not -0.0: zero must already be canonicalized to +0.0.

NotNan has a public type invariant (“only non-NaN 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 NotNan 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 NotNan value that breaks its invariant this way).

pub const fn into_inner(self) -> T

Returns the wrapped value.

Examples

use range_set_blaze::NotNanF64;

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

pub fn after(self) -> Self

Returns the next float, in total order.

Examples

use range_set_blaze::NotNanF64;

assert_eq!(NotNanF64::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 NotNan value that breaks its invariant this way).

pub fn before(self) -> Self

Returns the previous float, in total order.

Examples

use range_set_blaze::NotNanF64;

assert_eq!(NotNanF64::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 NotNan 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::NotNanF64;

let value = NotNanF64::new(42.0);
assert_eq!(value.checked_after(), Some(value.after()));
let value = NotNanF64::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::NotNanF64;

let value = NotNanF64::new(42.0);
assert_eq!(value.checked_before(), Some(value.before()));
let value = NotNanF64::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 NotNan range.

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

Examples

use range_set_blaze::{RangeSetBlaze, NotNanF64};

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

Panics

Panics if start or end is NaN.

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 NotNan ranges.

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

Examples

use range_set_blaze::{RangeSetBlaze, NotNanF64};

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

Panics

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

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

where I: IntoIterator<Item = T>,

Convenience method to convert primitive values into ordered NotNan values.

Examples

use range_set_blaze::{RangeSetBlaze, NotNanF64};

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

Panics

Panics (when iterated) if any value is NaN.

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

Views primitive values as ordered NotNan 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, NotNanF64};

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

Panics

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

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

Views primitive values as ordered NotNan 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 not NaN 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.

NotNan 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 NotNan::new_unchecked for the full rationale).

Trait Implementations

impl<T: Clone + NotNanFloat> Clone for NotNan<T>

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

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T: Copy + NotNanFloat> Copy for NotNan<T>

impl<T: Debug + NotNanFloat> Debug for NotNan<T>

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

Formats the value using the given formatter.

impl<T: Default + NotNanFloat> Default for NotNan<T>

fn default() -> NotNan<T>

Returns the “default value” for a type.

impl<T: NotNanFloat> Eq for NotNan<T>

impl<T: NotNanFloat> Hash for NotNan<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: NotNanFloat> Integer for NotNan<T>

type SafeLen = <T as NotNanFloat>::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>

Available on crate feature from_slice only.

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: NotNanFloat> Ord for NotNan<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.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl<T: NotNanFloat> PartialEq for NotNan<T>

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

Equality operator ==.

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

Inequality operator !=.

impl<T: NotNanFloat> PartialOrd for NotNan<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.