Trait FixedSignedCast

pub trait FixedSignedCast: FixedPointNumber {
    type Signed: FixedPointNumber;

    // Required methods
    fn saturating<F>(x: Self, f: F) -> Self
       where F: FnOnce(Self::Signed) -> Self::Signed;
    fn checked<F>(x: Self, f: F) -> Option<Self>
       where F: FnOnce(Option<Self::Signed>) -> Self::Signed;
    fn checked_into(x: Self) -> Option<Self::Signed>;
    fn saturated_into(x: Self) -> Self::Signed;
    fn checked_from(x: Self::Signed) -> Option<Self>;
    fn saturated_from(x: Self::Signed) -> Self;
}

A bridge that allows any [FixedPointNumber] type - including unsigned ones - to perform arithmetic in a signed intermediate space, then project the result back to the original type.

Motivation

Several mathematical operations (logarithm of a fraction, negative exponents, complex-domain arithmetic) require signed intermediates even when the input and final result are both representable as unsigned values. Rather than duplicating signed-aware implementations for every function, FixedSignedCast provides a single seam:

• Signed types (FixedI64, FixedI128) implement this trait as a pure identity: the associated Signed type is Self, and every conversion is a no-op.
• Unsigned types (FixedU64, FixedU128) map to a wider signed counterpart (FixedI128) that can represent the full unsigned range as non-negative values. Conversions to/from Signed clamp or fail gracefully when a result is negative (i.e. not representable by the unsigned type).

Associated Type

• Signed - the signed fixed-point type used as the arithmetic workspace. For signed types this is Self, for unsigned types it is FixedI128.

Methods

Method	Behaviour on error / out-of-range
saturating	Clamps the result to the target type’s bounds
checked	Returns None when the result is out-of-range
checked_into	Self -> Option<Signed>
saturated_into	Self -> Signed (clamping on overflow)
checked_from	Signed -> Option<Self>
saturated_from	Signed -> Self (clamping on underflow/overflow)

Usage

Prefer FixedSignedCast::saturating for operations where out-of-range results should clamp silently, and FixedSignedCast::checked where out-of-range results must be propagated to the caller as None.

Required Associated Types

type Signed: FixedPointNumber

The signed fixed-point workspace type for intermediate arithmetic.

• Signed types (FixedI64, FixedI128): type Signed = Self.
• Unsigned types (FixedU64, FixedU128): type Signed = FixedI128.

Required Methods

fn saturating<F>(x: Self, f: F) -> Self

where F: FnOnce(Self::Signed) -> Self::Signed,

Applies the closure f in Signed space and converts the result back to Self, clamping at the type’s representable bounds on overflow or underflow.

Useful when signed arithmetic may produce a value outside the target range but a best-effort saturated answer is acceptable.

fn checked<F>(x: Self, f: F) -> Option<Self>

where F: FnOnce(Option<Self::Signed>) -> Self::Signed,

Applies the closure f in Signed space and converts the result back to Self, returning None when the result cannot be represented.

The closure receives an Option<Signed> - None signals that the initial conversion from Self into Signed already failed (only possible for FixedU128 values exceeding i128::MAX).

fn checked_into(x: Self) -> Option<Self::Signed>

Converts Self into Signed, returning None if the value cannot be represented in Signed.

For signed types this is always Some(x). For unsigned types, this fails only when x.into_inner() > i128::MAX (only reachable with FixedU128 values in the upper half of its range).

fn saturated_into(x: Self) -> Self::Signed

Converts Self into Signed, clamping to Signed::max_value() on overflow.

For signed types this is a zero-cost identity. For unsigned types the inner u64/u128 value is reinterpreted as i128; values that exceed i128::MAX clamp to i128::MAX.

fn checked_from(x: Self::Signed) -> Option<Self>

Converts a Signed value into Self, returning None if the value falls outside the representable range of Self.

For signed types this is always Some(x). For unsigned types, a negative Signed inner value means the result is negative and therefore unrepresentable - None is returned.

fn saturated_from(x: Self::Signed) -> Self

Converts a Signed value into Self, clamping at the type bounds.

For signed types this is a zero-cost identity. For unsigned types, negative values clamp to 0. No upper clamp is needed: a non-negative i128 inner value is at most i128::MAX = 2^127 - 1, which is always less than u128::MAX = 2^128 - 1, so it always fits in the unsigned inner type without loss.

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 FixedSignedCast for FixedI64

Identity implementation for FixedI64.

FixedI64 is already signed, so checked_into, saturated_into, checked_from, and saturated_from are all zero-cost identity operations.

saturating delegates directly to f - any saturation that occurs inside the closure is the closure’s own saturating arithmetic, which is the expected behaviour for this variant.

checked delegates to f and returns None only when the result has saturated to min_value() or max_value(), which are the two sentinel values that saturating arithmetic produces on overflow. If the closure legitimately computes exactly min_value() or max_value(), None is returned conservatively. For cases where that distinction matters, prefer the saturating variant and handle clamping at the call site.

type Signed = FixedI64

fn saturating<F>(x: Self, f: F) -> Self

where F: FnOnce(Self::Signed) -> Self::Signed,

fn checked<F>(x: Self, f: F) -> Option<Self>

where F: FnOnce(Option<Self::Signed>) -> Self::Signed,

fn checked_into(x: Self) -> Option<Self::Signed>

fn saturated_into(x: Self) -> Self::Signed

fn checked_from(x: Self::Signed) -> Option<Self>

fn saturated_from(x: Self::Signed) -> Self

impl FixedSignedCast for FixedI128

Identity implementation for FixedI128.

FixedI128 is already signed, so checked_into, saturated_into, checked_from, and saturated_from are all zero-cost identity operations.

saturating delegates directly to f - any saturation that occurs inside the closure is the closure’s own saturating arithmetic, which is the expected behaviour for this variant.

checked delegates to f and returns None only when the result has saturated to min_value() or max_value(), which are the two sentinel values that saturating arithmetic produces on overflow. If the closure legitimately computes exactly min_value() or max_value(), None is returned conservatively. For cases where that distinction matters, prefer the saturating variant and handle clamping at the call site.

type Signed = FixedI128

fn saturating<F>(x: Self, f: F) -> Self

where F: FnOnce(Self::Signed) -> Self::Signed,

fn checked<F>(x: Self, f: F) -> Option<Self>

where F: FnOnce(Option<Self::Signed>) -> Self::Signed,

fn checked_into(x: Self) -> Option<Self::Signed>

fn saturated_into(x: Self) -> Self::Signed

fn checked_from(x: Self::Signed) -> Option<Self>

fn saturated_from(x: Self::Signed) -> Self

impl FixedSignedCast for FixedU64

Unsigned-to-signed bridge for FixedU64.

Uses FixedI128 as the signed workspace. A FixedU64 inner value is a u64, which always fits in i128, so checked_into / saturated_into are infallible. The reverse (checked_from / saturated_from) can fail or clamp when the signed result is negative or exceeds u64::MAX.

type Signed = FixedI128

fn saturating<F>(x: Self, f: F) -> Self

where F: FnOnce(Self::Signed) -> Self::Signed,

fn checked<F>(x: Self, f: F) -> Option<Self>

where F: FnOnce(Option<Self::Signed>) -> Self::Signed,

fn checked_into(x: Self) -> Option<Self::Signed>

fn saturated_into(x: Self) -> Self::Signed

fn checked_from(x: Self::Signed) -> Option<Self>

fn saturated_from(x: Self::Signed) -> Self

impl FixedSignedCast for FixedU128

Unsigned-to-signed bridge for FixedU128.

Uses FixedI128 as the signed workspace. Unlike FixedU64, a FixedU128 inner value is a u128 whose upper half (> i128::MAX) cannot be represented in i128. checked_into therefore returns None for those values, and saturated_into clamps them to i128::MAX.

type Signed = FixedI128

fn saturating<F>(x: Self, f: F) -> Self

where F: FnOnce(Self::Signed) -> Self::Signed,

fn checked<F>(x: Self, f: F) -> Option<Self>

where F: FnOnce(Option<Self::Signed>) -> Self::Signed,

fn checked_into(x: Self) -> Option<Self::Signed>

fn saturated_into(x: Self) -> Self::Signed

fn checked_from(x: Self::Signed) -> Option<Self>

fn saturated_from(x: Self::Signed) -> Self

Implementors