Trait RawRealTrait 

pub trait RawRealTrait:
    RawScalarTrait<ValidationErrors = ErrorsValidationRawReal<Self>>
    + PartialOrd
    + PartialOrd<f64>
    + Sign
    + Rounding {
    type RawComplex: RawComplexTrait<RawReal = Self>;

    // Required methods
    fn unchecked_abs(self) -> Self;
    fn unchecked_atan2(self, denominator: &Self) -> Self;
    fn unchecked_pow_exponent_real(self, exponent: &Self) -> Self;
    fn unchecked_hypot(self, other: &Self) -> Self;
    fn unchecked_ln_1p(self) -> Self;
    fn unchecked_exp_m1(self) -> Self;
    fn unchecked_mul_add_mul_mut(
        &mut self,
        mul: &Self,
        add_mul1: &Self,
        add_mul2: &Self,
    );
    fn unchecked_mul_sub_mul_mut(
        &mut self,
        mul: &Self,
        sub_mul1: &Self,
        sub_mul2: &Self,
    );
    fn raw_total_cmp(&self, other: &Self) -> Ordering;
    fn raw_clamp(self, min: &Self, max: &Self) -> Self;
    fn raw_classify(&self) -> FpCategory;
    fn raw_two(precision: u32) -> Self;
    fn raw_one_div_2(precision: u32) -> Self;
    fn raw_pi(precision: u32) -> Self;
    fn raw_two_pi(precision: u32) -> Self;
    fn raw_pi_div_2(precision: u32) -> Self;
    fn raw_max_finite(precision: u32) -> Self;
    fn raw_min_finite(precision: u32) -> Self;
    fn raw_epsilon(precision: u32) -> Self;
    fn raw_ln_2(_precision: u32) -> Self;
    fn raw_ln_10(_precision: u32) -> Self;
    fn raw_log10_2(_precision: u32) -> Self;
    fn raw_log2_10(_precision: u32) -> Self;
    fn raw_log2_e(_precision: u32) -> Self;
    fn raw_log10_e(_precision: u32) -> Self;
    fn raw_e(_precision: u32) -> Self;
    fn try_new_raw_real_from_f64<RealPolicy: ValidationPolicyReal<Value = Self>>(
        value: f64,
    ) -> Result<Self, ErrorsTryFromf64<Self>>;
    fn precision(&self) -> u32;
    fn compute_hash<H: Hasher>(&self, state: &mut H);
    fn truncate_to_usize(
        self,
    ) -> Result<usize, ErrorsRawRealToInteger<Self, usize>>;
}

A trait for raw real scalar types, extending RawScalarTrait with real-specific operations.

This trait defines the fundamental operations for real number types without validation or safety checks. Implementations should assume inputs are valid and focus on computational efficiency.

This trait is implemented by the underlying real number types within a kernel, such as f64 or rug::Float. It builds upon RawScalarTrait by adding operations that are unique to real numbers, like atan2, and by enforcing an ordering relationship.

Hashing Support

Types implementing this trait must provide a compute_hash method that:

• Produces consistent hash values for mathematically equal numbers
• Handles floating-point edge cases (like signed zeros) correctly
• Maintains the contract that a == b implies hash(a) == hash(b)

This enables validated wrapper types to implement Hash when appropriate validation policies guarantee finite values.

Trait Bounds

• RawScalarTrait<ValidationErrors = ErrorsValidationRawReal<Self>>: Ensures that the type is a raw scalar and that its validation error type is the standard one for real numbers.
• PartialOrd: Requires that the type can be partially ordered, which is fundamental for real numbers.
• PartialOrd<f64>: These crucial bounds allow instances of the raw real type to be directly compared with f64 constants. This is essential for implementing domain checks (e.g., value < 0.0 or value >= 0.0) that work across both f64 and rug::Float without extra conversions.

Associated Types

• type RawComplex: RawComplexTrait<RawReal = Self>: This links the raw real type to its corresponding complex number representation. For example, for f64, this would be num::Complex<f64>. This association is vital for operations that can transition from the real to the complex domain.

Required Associated Types

type RawComplex: RawComplexTrait<RawReal = Self>

The associated complex type that uses this type as its real part.

Required Methods

fn unchecked_abs(self) -> Self

Computes the absolute value of self without validation.

Contract: The caller must ensure that the input value has already been validated and is suitable for the operation.

fn unchecked_atan2(self, denominator: &Self) -> Self

Computes the four-quadrant arctangent of self (y) and denominator (x) without validation.

Contract: The caller must ensure that self and denominator are not both zero.

fn unchecked_pow_exponent_real(self, exponent: &Self) -> Self

Raises self to the power of a real exponent without validation.

Contract: The caller must ensure the inputs are valid for the power function. For example, if self is negative, the exponent should be an integer, but this function does not enforce this.

fn unchecked_hypot(self, other: &Self) -> Self

fn unchecked_ln_1p(self) -> Self

fn unchecked_exp_m1(self) -> Self

fn unchecked_mul_add_mul_mut( &mut self, mul: &Self, add_mul1: &Self, add_mul2: &Self, )

Multiplies two pairs and adds them, rounding to the nearest. a.unchecked_mul_add_mul_mut(&b, &c, &d) produces a result like &a * &b + &c * &d, but stores the result in a using its precision.

Contract: The caller must ensure all inputs are valid.

fn unchecked_mul_sub_mul_mut( &mut self, mul: &Self, sub_mul1: &Self, sub_mul2: &Self, )

Multiplies two pairs and subtracts them, rounding to the nearest. a.unchecked_mul_sub_mul_mut(&b, &c, &d) produces a result like &a * &b - &c * &d, but stores the result in a using its precision.

Contract: The caller must ensure all inputs are valid.

fn raw_total_cmp(&self, other: &Self) -> Ordering

fn raw_clamp(self, min: &Self, max: &Self) -> Self

Clamps the value within the specified bounds.

fn raw_classify(&self) -> FpCategory

fn raw_two(precision: u32) -> Self

fn raw_one_div_2(precision: u32) -> Self

fn raw_pi(precision: u32) -> Self

fn raw_two_pi(precision: u32) -> Self

fn raw_pi_div_2(precision: u32) -> Self

fn raw_max_finite(precision: u32) -> Self

fn raw_min_finite(precision: u32) -> Self

fn raw_epsilon(precision: u32) -> Self

fn raw_ln_2(_precision: u32) -> Self

fn raw_ln_10(_precision: u32) -> Self

fn raw_log10_2(_precision: u32) -> Self

fn raw_log2_10(_precision: u32) -> Self

fn raw_log2_e(_precision: u32) -> Self

fn raw_log10_e(_precision: u32) -> Self

fn raw_e(_precision: u32) -> Self

fn try_new_raw_real_from_f64<RealPolicy: ValidationPolicyReal<Value = Self>>( value: f64, ) -> Result<Self, ErrorsTryFromf64<Self>>

fn precision(&self) -> u32

Returns the precision (in bits) of the raw real type.

fn compute_hash<H: Hasher>(&self, state: &mut H)

Computes a hash value for this real number.

This method must ensure that mathematically equal values produce the same hash, even across different representations (e.g., +0.0 and -0.0).

fn truncate_to_usize(self) -> Result<usize, ErrorsRawRealToInteger<Self, usize>>

Safely truncates the real number and converts it to a usize.

This function first truncates the number towards zero (discarding any fractional part) and then attempts to convert the result to a usize. The conversion is fallible and returns a detailed error if the value cannot be represented as a usize.

Returns

• Ok(usize): If the truncated value is within the valid range of usize (i.e., 0 <= value <= usize::MAX).
• Err(ErrorsRawRealToInteger): If the conversion fails, with a variant indicating the reason:
  • NotFinite: If the original value is NaN or Infinity.
  • OutOfRange: If the truncated value is negative or exceeds usize::MAX.

Note

The NotAnInteger error variant is not returned by this function because the truncation step explicitly handles the fractional part.

Examples

Success

let value = 42.9_f64;
assert_eq!(value.truncate_to_usize().unwrap(), 42);

let zero = 0.0_f64;
assert_eq!(zero.truncate_to_usize().unwrap(), 0);

Failure

// Value is negative
let negative_value = -10.5_f64;
assert!(matches!(negative_value.truncate_to_usize(), Err(ErrorsRawRealToInteger::OutOfRange { .. })));

// Value is too large for usize
let large_value = (usize::MAX as f64) + 100.0;
assert!(matches!(large_value.truncate_to_usize(), Err(ErrorsRawRealToInteger::OutOfRange { .. })));

// Value is not finite
let nan_value = f64::NAN;
assert!(matches!(nan_value.truncate_to_usize(), Err(ErrorsRawRealToInteger::NotFinite { .. })));

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl RawRealTrait for f64

fn unchecked_mul_add_mul_mut( &mut self, mul: &Self, add_mul1: &Self, add_mul2: &Self, )

Multiplies two pairs and adds them in one fused operation, rounding to the nearest with only one rounding error. a.unchecked_mul_add_mul_mut(&b, &c, &d) produces a result like &a * &b + &c * &d, but stores the result in a using its precision.

fn unchecked_mul_sub_mul_mut( &mut self, mul: &Self, sub_mul1: &Self, sub_mul2: &Self, )

Multiplies two pairs and subtracts them in one fused operation, rounding to the nearest with only one rounding error. a.unchecked_mul_sub_mul_mut(&b, &c, &d) produces a result like &a * &b - &c * &d, but stores the result in a using its precision.

fn raw_clamp(self, min: &Self, max: &Self) -> Self

Clamps the value within the specified bounds.

type RawComplex = Complex<f64>

fn unchecked_abs(self) -> f64

fn unchecked_atan2(self, denominator: &Self) -> Self

fn unchecked_pow_exponent_real(self, exponent: &Self) -> Self

fn unchecked_hypot(self, other: &Self) -> Self

fn unchecked_ln_1p(self) -> Self

fn unchecked_exp_m1(self) -> Self

fn raw_total_cmp(&self, other: &Self) -> Ordering

fn raw_classify(&self) -> FpCategory

fn raw_two(_precision: u32) -> Self

fn raw_one_div_2(_precision: u32) -> Self

fn raw_pi(_precision: u32) -> Self

fn raw_two_pi(_precision: u32) -> Self

fn raw_pi_div_2(_precision: u32) -> Self

fn raw_max_finite(_precision: u32) -> Self

fn raw_min_finite(_precision: u32) -> Self

fn raw_epsilon(_precision: u32) -> Self

fn raw_ln_2(_precision: u32) -> Self

fn raw_ln_10(_precision: u32) -> Self

fn raw_log10_2(_precision: u32) -> Self

fn raw_log2_10(_precision: u32) -> Self

fn raw_log2_e(_precision: u32) -> Self

fn raw_log10_e(_precision: u32) -> Self

fn raw_e(_precision: u32) -> Self

fn try_new_raw_real_from_f64<RealPolicy: ValidationPolicyReal<Value = Self>>( value: f64, ) -> Result<Self, ErrorsTryFromf64<f64>>

fn precision(&self) -> u32

fn compute_hash<H: Hasher>(&self, state: &mut H)

fn truncate_to_usize(self) -> Result<usize, ErrorsRawRealToInteger<f64, usize>>

impl RawRealTrait for Float

fn unchecked_mul_add_mul_mut( &mut self, mul: &Self, add_mul1: &Self, add_mul2: &Self, )

Multiplies two pairs and adds them in one fused operation, rounding to the nearest with only one rounding error. a.unchecked_mul_add_mul_mut(&b, &c, &d) produces a result like &a * &b + &c * &d, but stores the result in a using its precision.

fn unchecked_mul_sub_mul_mut( &mut self, mul: &Self, sub_mul1: &Self, sub_mul2: &Self, )

Multiplies two pairs and subtracts them in one fused operation, rounding to the nearest with only one rounding error. a.unchecked_mul_sub_mul_mut(&b, &c, &d) produces a result like &a * &b - &c * &d, but stores the result in a using its precision.

fn raw_clamp(self, min: &Self, max: &Self) -> Self

Clamps the value within the specified bounds.

type RawComplex = Complex

fn unchecked_abs(self) -> Float

fn unchecked_atan2(self, denominator: &Self) -> Self

fn unchecked_pow_exponent_real(self, exponent: &Self) -> Self

fn unchecked_hypot(self, other: &Self) -> Self

fn unchecked_ln_1p(self) -> Self

fn unchecked_exp_m1(self) -> Self

fn raw_total_cmp(&self, other: &Self) -> Ordering

fn raw_classify(&self) -> FpCategory

fn raw_two(precision: u32) -> Self

fn raw_one_div_2(precision: u32) -> Self

fn raw_pi(precision: u32) -> Self

fn raw_two_pi(precision: u32) -> Self

fn raw_pi_div_2(precision: u32) -> Self

fn raw_max_finite(precision: u32) -> Self

fn raw_min_finite(precision: u32) -> Self

fn raw_epsilon(precision: u32) -> Self

fn raw_ln_2(precision: u32) -> Self

fn raw_ln_10(precision: u32) -> Self

fn raw_log10_2(precision: u32) -> Self

fn raw_log2_10(precision: u32) -> Self

fn raw_log2_e(precision: u32) -> Self

fn raw_log10_e(precision: u32) -> Self

fn raw_e(precision: u32) -> Self

fn try_new_raw_real_from_f64<RealPolicy: ValidationPolicyReal<Value = Self>>( value: f64, ) -> Result<Self, ErrorsTryFromf64<Self>>

fn precision(&self) -> u32

fn compute_hash<H: Hasher>(&self, state: &mut H)

fn truncate_to_usize( self, ) -> Result<usize, ErrorsRawRealToInteger<Float, usize>>

Implementors