Trait RealScalar 

pub trait RealScalar:
    FpScalar<RealType = Self, InnerType = Self::RawReal>
    + Sign
    + Rounding
    + Constants
    + PartialEq<f64>
    + PartialOrd
    + PartialOrd<f64>
    + Max
    + Min
    + ATan2
    + for<'a> Pow<&'a Self, Error = PowRealBaseRealExponentErrors<Self::RawReal>>
    + Clamp
    + Classify
    + ExpM1
    + Hypot
    + Ln1p
    + TotalCmp {
    type RawReal: RawRealTrait;

    // Required methods
    fn kernel_mul_add_mul_mut(
        &mut self,
        mul: &Self,
        add_mul1: &Self,
        add_mul2: &Self,
    );
    fn kernel_mul_sub_mul_mut(
        &mut self,
        mul: &Self,
        sub_mul1: &Self,
        sub_mul2: &Self,
    );
    fn try_from_f64(value: f64) -> Result<Self, ErrorsTryFromf64<Self::RawReal>>;
}

Trait for scalar real numbers

RealScalar extends the fundamental FpScalar trait, providing an interface specifically for real (non-complex) floating-point numbers. It introduces operations and properties that are unique to real numbers, such as ordering, rounding, and clamping.

This trait is implemented by real scalar types within each numerical kernel, for example, f64 for the native kernel, and RealRugStrictFinite for the rug kernel (when the rug feature is enabled).

Key Concepts

• Inheritance from FpScalar: As a sub-trait of FpScalar, any RealScalar type automatically gains all the capabilities of a general floating-point number, including basic arithmetic and standard mathematical functions (e.g., sin, exp, sqrt).

• Raw Underlying Type (RawReal): This associated type specifies the most fundamental, “raw” representation of the real number, which implements the RawRealTrait. This is the type used for low-level, unchecked operations within the library’s internal implementation.

  • For f64, RealNative64StrictFinite and RealNative64StrictFiniteInDebug, RawReal is f64.
  • For RealRugStrictFinite<P>, RawReal is rug::Float.

Provided Operations

In addition to the functions from FpScalar, RealScalar provides a suite of methods common in real number arithmetic, sourced from its super-traits:

• Rounding (Rounding): kernel_ceil(), kernel_floor(), kernel_round(), kernel_round_ties_even(), kernel_trunc(), and kernel_fract().

• Sign Manipulation (Sign): kernel_copysign(), kernel_signum(), kernel_is_sign_positive(), and kernel_is_sign_negative().

• Comparison and Ordering:

  • From Max/Min: max() and min().
  • From TotalCmp: total_cmp() for a total ordering compliant with IEEE 754.
  • From Clamp: kernel_clamp().

• Specialized Functions:

  • From ATan2: atan2().
  • From ExpM1/Ln1p: kernel_exp_m1() and kernel_ln_1p().
  • From Hypot: kernel_hypot(); // sqrt(aa + bb)
  • From Classify: kernel_classify().

• Fused Multiply-Add Variants: kernel_mul_add_mul_mut() and kernel_mul_sub_mul_mut().

• Constants and Constructors:

  • From Constants: epsilon(), pi(), max_finite(), etc.
  • Fallible constructor from f64: try_from_f64(), which validates the input for finiteness and, for arbitrary-precision types, exact representability.

Naming Convention for kernel_* Methods

Methods prefixed with kernel_ (e.g., kernel_ceil, kernel_copysign) are part of the low-level kernel interface. They typically delegate directly to the most efficient implementation for the underlying type (like f64::ceil) without adding extra validation layers. They are intended to be fast primitives upon which safer, higher-level abstractions can be built.

Critical Trait Bounds

• Self: FpScalar<RealType = Self>: This is the defining constraint. It ensures that the type has all basic floating-point capabilities and confirms that its associated real type is itself.
• Self: PartialOrd + PartialOrd<f64>: These bounds are essential for comparison operations, allowing instances to be compared both with themselves and with native f64 constants.

Required Associated Types

type RawReal: RawRealTrait

The most fundamental, “raw” representation of this real number.

For example:

• For f64, this is f64.
• For RealRugStrictFinite<P>, this is rug::Float (with precision P).

This type is used to parameterize ErrorsValidationRawReal for this scalar’s raw validation errors.

Required Methods

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

Multiplies two products and adds them in one fused operation, rounding to the nearest with only one rounding error. a.kernel_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 kernel_mul_sub_mul_mut( &mut self, mul: &Self, sub_mul1: &Self, sub_mul2: &Self, )

Multiplies two products and subtracts them in one fused operation, rounding to the nearest with only one rounding error. a.kernel_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 try_from_f64(value: f64) -> Result<Self, ErrorsTryFromf64<Self::RawReal>>

Tries to create an instance of Self from a f64.

This conversion is fallible and validates the input value. For rug-based types, it also ensures that the f64 can be represented exactly at the target precision.

Errors

Returns ErrorsTryFromf64 if the value is not finite or cannot be represented exactly by Self.

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 RealScalar for f64

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

Multiplies two products and adds them in one fused operation, rounding to the nearest with only one rounding error. a.kernel_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 kernel_mul_sub_mul_mut( &mut self, mul: &Self, sub_mul1: &Self, sub_mul2: &Self, )

Multiplies two products and subtracts them in one fused operation, rounding to the nearest with only one rounding error. a.kernel_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 try_from_f64(value: f64) -> Result<Self, ErrorsTryFromf64<f64>>

Try to build a f64 instance from a f64. The returned value is Ok if the input value is finite, otherwise the returned value is ErrorsTryFromf64.

type RawReal = f64

Implementors

impl<K: NumKernel> RealScalar for RealValidated<K>

type RawReal = <K as RawKernel>::RawReal