Struct Wide 

pub struct Wide(/* private fields */);

A product of two Fixed values, kept at full width: Q95.32 in an i128.

Why this exists

Fixed::saturating_mul narrows its i128 product back to an i64, which is right for arithmetic that stays in the world and wrong for geometry that squares things twice. Ray-versus-sphere forms b² − 4ac where a and c are themselves squared lengths; at ordinary game scales a·c overflows a Fixed long before the ray does anything unusual, and the result saturates — deterministically, and to the wrong number.

So the narrowing is deferred. A product of two full-range Fixed values needs 126 bits and an i128 holds 127, which means a single wide_mul can never overflow, for any inputs at all. Sums of a few of them cannot either at any scale a world reaches.

Contract

• 32 fractional bits, being the sum of its operands’ sixteen. That is not an implementation detail: it is why Wide::sqrt needs no shift.
• Ordering is exact, so comparing two products — which is most of what geometry does with them — never rounds at all.
• Narrowing is explicit, and says whether it lost anything.

Implementations

impl Wide

pub const ZERO: Self

Zero.

pub const fn to_bits(self) -> i128

The raw Q95.32 pattern.

There is no from_bits counterpart, deliberately. A Wide is an intermediate rather than state: it is produced by a multiply and consumed by a root, a comparison or a narrowing, and nothing serialises one. An unused constructor is a promise to keep working that nobody asked for.

pub const fn signum(self) -> i32

−1, 0 or 1.

pub fn sqrt(self) -> Fixed

The square root, as a Fixed.

No shift, and that is the point of 32 fractional bits. A Wide holding the real value v has raw pattern v · 2³², whose integer square root is √v · 2¹⁶ — exactly a Fixed’s raw pattern. Squaring and then rooting therefore loses nothing to scaling, where the narrow path had to shift left by sixteen first and could overflow doing it.

Floor-exact, by u128::isqrt’s own contract.

Panics

If negative. See Wide::checked_sqrt.

pub fn checked_sqrt(self) -> Option<Fixed>

The square root, or None if negative — which a discriminant is, routinely, and which is a miss rather than a mistake.

pub const fn checked_narrow(self) -> Option<Fixed>

Back to a Fixed, or None if it will not fit.

Trait Implementations

impl Add for Wide

type Output = Wide

The resulting type after applying the + operator.

fn add(self, other: Self) -> Self

Performs the + operation.

impl Clone for Wide

fn clone(&self) -> Wide

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Copy for Wide

impl Debug for Wide

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

Formats the value using the given formatter.

impl Default for Wide

fn default() -> Wide

Returns the “default value” for a type.

impl Eq for Wide

impl Hash for Wide

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 Neg for Wide

type Output = Wide

The resulting type after applying the - operator.

fn neg(self) -> Self

Performs the unary - operation.

impl Ord for Wide

fn cmp(&self, other: &Wide) -> 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.

impl PartialEq for Wide

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

Equality operator ==.

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

Inequality operator !=.

impl PartialOrd for Wide

fn partial_cmp(&self, other: &Wide) -> 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 StructuralPartialEq for Wide

impl Sub for Wide

type Output = Wide

The resulting type after applying the - operator.

fn sub(self, other: Self) -> Self

Performs the - operation.