Struct HashableScalar 

pub struct HashableScalar<ScalarType: FpScalar> { /* private fields */ }

Wrapper type that makes floating-point scalars hashable for use in hash-based collections.

Purpose

Real or complex floating-point types (f32, f64, Complex<f32>, Complex<f64> and validated wrappers like RealNative64StrictFinite, ComplexNative64StrictFinite, RealRugStrictFinite<PRECISION>, ComplexRugStrictFinite<PRECISION>, etc.) are not hashable by default in Rust because of the presence of NaN values, which violate the requirements for hashing. Specifically, IEEE 754 defines that NaN != NaN, which means that two identical NaN values would not be considered equal, leading to inconsistent hashing behavior. do not implement Hash by default because IEEE 754 defines NaN != NaN, violating the requirement that a == b implies hash(a) == hash(b). This type enforces that only finite floating-point values can be hashed, making them safe for use in:

• HashMap and HashSet
• DashMap for concurrent caching
• Any algorithm requiring consistent hashing of numerical values

Invariants

• Only finite values allowed: HashableScalar::try_new() rejects values that are not finite (not NaN or ±∞).
• Hash consistency: Values are hashed via their raw bit representation (RawScalarTrait::compute_hash_raw_scalar), ensuring bitwise-identical values produce identical hashes.
• Equality semantics: Implements Eq by delegating to the underlying scalar’s PartialEq, which is safe because we exclude NaN.

Type Parameters

• ScalarType: Any real or complex floating-point type implementing FpScalar (e.g., f64, Complex<f64>, RealNative64StrictFinite, ComplexNative64StrictFinite, RealRugStrictFinite<PRECISION>, ComplexRugStrictFinite<PRECISION>, etc.).

Examples

Basic Usage with f64 and Complex<f64>

use num_valid::scalars::HashableScalar;
use num::Complex;
use std::collections::HashSet;

let x = HashableScalar::new(3.14);
let y = HashableScalar::new(2.71);
let z = HashableScalar::new(3.14);

let mut set_real = HashSet::new();
set_real.insert(x);
set_real.insert(y);
set_real.insert(z); // Duplicate, won't be added

assert_eq!(set_real.len(), 2);

let a = HashableScalar::new(Complex::new(3.14, 2.0));
let b = HashableScalar::new(Complex::new(2.71, 1.0));
let c = HashableScalar::new(Complex::new(3.14, 2.0));

let mut set_complex = HashSet::new();
set_complex.insert(a);
set_complex.insert(b);
set_complex.insert(c); // Duplicate, won't be added

assert_eq!(set_complex.len(), 2);

Use in Caching Structures

use num_valid::scalars::HashableScalar;
use std::collections::HashMap;

// Cache computed values indexed by floating-point parameters
let mut cache: HashMap<HashableScalar<f64>, String> = HashMap::new();

let key = HashableScalar::new(1.5);
cache.insert(key, "result_for_1.5".to_string());

let retrieved = cache.get(&HashableScalar::new(1.5));
assert_eq!(retrieved, Some(&"result_for_1.5".to_string()));

With Validated Scalar Types

The wrapper works with any type implementing FpScalar, including validated types from the num_valid crate:

use num_valid::scalars::HashableScalar;
use std::collections::HashSet;

// Works with any FpScalar type
let mut set = HashSet::new();
set.insert(HashableScalar::new(1.0_f64));
set.insert(HashableScalar::new(2.0_f64));
set.insert(HashableScalar::new(1.0_f64)); // Duplicate

assert_eq!(set.len(), 2);

Invalid Values

Fallible construction rejects non-finite values:

use num_valid::scalars::HashableScalar;

let invalid = HashableScalar::try_new(f64::NAN);
assert!(invalid.is_err());

Implementation Notes

• Serialization: Supports serde serialization/deserialization with bounds to ensure the wrapped type can be serialized.
• Extraction: Implements IntoInner for consuming the wrapper and extracting the underlying scalar via .into_inner().
• Zero-cost abstraction: The wrapper is #[repr(transparent)] equivalent (single field), so there is no runtime overhead.

See Also

• FpScalar for the trait bounds on wrapped types
• RawScalarTrait::compute_hash_raw_scalar for the hashing mechanism
• Caching examples in numerics-core/src/math/chebyshev/cache.rs

Implementations

impl<ScalarType: FpScalar> HashableScalar<ScalarType>

pub fn new(value: ScalarType) -> Self

Creates a new hashable scalar from a finite value.

Panics

Panics if the value is not finite (NaN or infinite). Use Self::try_new when the input is not already trusted.

pub fn try_new(value: ScalarType) -> Result<Self, ErrorsHashableScalar>

Attempts to create a hashable scalar from a finite value.

Returns ErrorsHashableScalar::NonFiniteValue when value is NaN or infinite.

Trait Implementations

impl<ScalarType: FpScalar> AsRef<ScalarType> for HashableScalar<ScalarType>

fn as_ref(&self) -> &ScalarType

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

impl<ScalarType: Clone + FpScalar> Clone for HashableScalar<ScalarType>

fn clone(&self) -> HashableScalar<ScalarType>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<ScalarType: Debug + FpScalar> Debug for HashableScalar<ScalarType>

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

Formats the value using the given formatter.

impl<'de, ScalarType> Deserialize<'de> for HashableScalar<ScalarType>

where ScalarType: for<'a> Deserialize<'a> + FpScalar,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<ScalarType: FpScalar> Eq for HashableScalar<ScalarType>

impl<ScalarType: FpScalar> Hash for HashableScalar<ScalarType>

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<ScalarType: FpScalar> IntoInner for HashableScalar<ScalarType>

type InnerType = ScalarType

The type of the inner value that will be extracted.

fn into_inner(self) -> ScalarType

Consumes the wrapper and returns the inner value.

impl<ScalarType: PartialEq + FpScalar> PartialEq for HashableScalar<ScalarType>

fn eq(&self, other: &HashableScalar<ScalarType>) -> bool

Equality operator ==.

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

Inequality operator !=.

impl<ScalarType: PartialOrd + FpScalar> PartialOrd for HashableScalar<ScalarType>

fn partial_cmp(&self, other: &HashableScalar<ScalarType>) -> 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.

impl<ScalarType> Serialize for HashableScalar<ScalarType>

where ScalarType: Serialize + FpScalar,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<ScalarType: PartialEq + FpScalar> StructuralPartialEq for HashableScalar<ScalarType>