use crate::core::integer::*;
use crate::core::undefined::*;
use crate::{Circle, CircleConstants, Integer, Scalar, ScalarConstants};
use core::ops::{Shl, Shr};
use i256::I256;
use num_traits::{AsPrimitive, WrappingAdd, WrappingMul, WrappingNeg, WrappingSub};
macro_rules! impl_circle_new {
($($f:ty, $e:ty);*) => {
$(
impl Circle<$f, $e> {
/// Creates a new Circle from raw real, imaginary and exponent integers.
///
/// This is a low-level constructor that directly sets the internal state. For normal number creation, use `from()` which handles:
/// - Proper normalization of components
/// - Exponent adjustment
/// - Special value handling
///
/// ```
/// # use spirix::{Circle, CircleF5E3};
/// // new() directly sets the raw fields; use from() for automatic normalization let via_from = CircleF5E3::from(42_i32); let via_new = Circle::<i32, i8>::new(via_from.real, via_from.imaginary, via_from.exponent); assert!(via_new == via_from);
/// ```
#[inline]
pub fn new(real: $f, imaginary: $f, exponent: $e) -> Circle<$f, $e> {
Circle { real, imaginary, exponent }
}
}
)*
}
}
impl_circle_new! {
i8, i8;
i16, i8;
i32, i8;
i64, i8;
i128, i8;
i8, i16;
i16, i16;
i32, i16;
i64, i16;
i128, i16;
i8, i32;
i16, i32;
i32, i32;
i64, i32;
i128, i32;
i8, i64;
i16, i64;
i32, i64;
i64, i64;
i128, i64;
i8, i128;
i16, i128;
i32, i128;
i64, i128;
i128, i128
}
#[allow(private_bounds)]
impl<
F: Integer
+ FullInt
+ Shl<isize, Output = F>
+ Shr<isize, Output = F>
+ Shl<F, Output = F>
+ Shr<F, Output = F>
+ Shl<E, Output = F>
+ Shr<E, Output = F>
+ WrappingNeg
+ WrappingAdd
+ WrappingSub
+ WrappingMul,
E: Integer
+ FullInt
+ Shl<isize, Output = E>
+ Shr<isize, Output = E>
+ Shl<E, Output = E>
+ Shr<E, Output = E>
+ Shl<F, Output = E>
+ Shr<F, Output = E>
+ WrappingNeg
+ WrappingAdd
+ WrappingSub
+ WrappingMul,
> Circle<F, E>
where
Circle<F, E>: CircleConstants,
Scalar<F, E>: ScalarConstants,
u8: AsPrimitive<F>,
u16: AsPrimitive<F>,
u32: AsPrimitive<F>,
u64: AsPrimitive<F>,
u128: AsPrimitive<F>,
usize: AsPrimitive<F>,
i8: AsPrimitive<F>,
i16: AsPrimitive<F>,
i32: AsPrimitive<F>,
i64: AsPrimitive<F>,
i128: AsPrimitive<F>,
isize: AsPrimitive<F>,
I256: From<F>,
u8: AsPrimitive<E>,
u16: AsPrimitive<E>,
u32: AsPrimitive<E>,
u64: AsPrimitive<E>,
u128: AsPrimitive<E>,
usize: AsPrimitive<E>,
i8: AsPrimitive<E>,
i16: AsPrimitive<E>,
i32: AsPrimitive<E>,
i64: AsPrimitive<E>,
i128: AsPrimitive<E>,
isize: AsPrimitive<E>,
I256: From<E>,
{
/// Translate one Circle stored component into a Scalar.
///
/// The two encodings put the magnitude bit at different positions: Circle N1 normal: mag at FRAC-2 (sign bit at FRAC-1 explicit) — value = c × 2^(k − FRAC + 2) Scalar N0 normal: mag at FRAC-1 (sign implicit in MSB complement) — value = inflate(c) × 2^(k − FRAC + 1) Circle / Scalar exploded: top-2-bit tag (01 / 10) at FRAC-1..FRAC-2 — patterns match across N0 and N1. Circle / Scalar vanished: top-3-bit tag (001 / 110) at FRAC-1..FRAC-3 — patterns match across N0 and N1. Normal needs an extra `+1` shift compared to a "just renormalize to leading_same=0" pass, because of the N1-vs-N0 sign-position offset; the over-shift is then compensated by lowering the exponent by `leading-1` binades. Escape classes need NO extra shift past renormalization, since their tag positions are the same in both encodings: exploded shifts by `leading-1`, vanished by `leading-2`. A pure-real/pure-imaginary normal Circle's silent component (c == 0) would otherwise hit `c << FRAC` and land at `{ fraction: 0, exponent: non-AMBIG }`, which fails `is_zero()` and gets misread as some sub-canonical Scalar — guard that case explicitly.
fn extract_component(&self, c: F) -> Scalar<F, E> {
if self.is_normal() {
if c == F::zero() {
return Scalar::<F, E>::ZERO;
}
let fb = Self::fraction_bits();
let leading: isize = c.leading_ones().max(c.leading_zeros()) as isize;
let shift_amount: isize = leading.wrapping_sub(1);
let shift_e: E = shift_amount.as_();
// Sub-canonical extraction underflow: the silent component normalized into a fraction whose own binade would land below MIN_NORMAL. The cycle-position subtract would wrap thru AMBIG and surface as a huge positive Scalar. Detect by `self.exp.into_unsigned() <= shift_amount` and re-shape the component to the N-2 vanished form at AMBIG (mag bit at FRAC-3, shift = leading - 2) instead. Underflow shift is always strictly less than FRAC (shift = leading - 2 ≤ FRAC - 2), so native `c << shift` is safe.
if shift_amount > 0 && self.exponent.into_unsigned() <= shift_e.into_unsigned() {
return Scalar {
fraction: c << leading.wrapping_sub(2),
exponent: Scalar::<F, E>::ambiguous_exponent(),
};
}
// leading == FRAC happens only when c is all-ones (the smallest sub-canonical negative magnitude like c=-1 in i8). Native `c << FRAC` masks the shift count to 0 and returns c unchanged, sign-flipping the N0 interpretation. The mathematically correct result is "all bits shift off the top" = 0.
let fraction: F = if leading >= fb {
F::zero()
} else {
c << leading
};
return Scalar {
fraction,
exponent: self.exponent.wrapping_sub(&shift_e),
};
}
if self.exploded() {
let leading: isize = c.leading_ones().max(c.leading_zeros()) as isize;
// exploded shift = leading - 1 ≤ FRAC - 1, always strictly < FRAC.
return Scalar {
fraction: c << leading.wrapping_sub(1),
exponent: Scalar::<F, E>::ambiguous_exponent(),
};
}
if self.vanished() {
let leading: isize = c.leading_ones().max(c.leading_zeros()) as isize;
// vanished shift = leading - 2 ≤ FRAC - 2, always strictly < FRAC.
return Scalar {
fraction: c << leading.wrapping_sub(2),
exponent: Scalar::<F, E>::ambiguous_exponent(),
};
}
Scalar {
fraction: c,
exponent: Scalar::<F, E>::ambiguous_exponent(),
}
}
/// Returns the real part of this Circle as a Scalar
///
/// # Description
///
/// Extracts the real component of this Circle as a Scalar value, preserving state information.
///
/// # Returns
///
/// - `[#,#]` ➔ `[#]` Real component as a normal Scalar
/// - `[0]` ➔ `[0]` Zero
/// - `[↑]` ➔ `[↑]` Real part as an exploded Scalar
/// - `[↓]` ➔ `[↓]` Real part as a vanished Scalar
/// - `[∞]` ➔ `[∞]` Infinity
/// - `[℘?]` ➔ `[℘?]` The same undefined state
///
/// # Examples
///
/// ```rust
/// use spirix::{Circle, CircleF5E3};
///
/// // Real part of a normal complex number let complex = Circle::<i32, i8>::from((3_i32, 4_i32)); assert!(complex.r() == 3_i32);
///
/// // Real part of Zero is Zero let zero = CircleF5E3::ZERO; assert!(zero.r().is_zero());
///
/// // Real part of exploded preserves state let exploded: CircleF5E3 = CircleF5E3::MAX * 2_i32; assert!(exploded.r().exploded());
///
/// // Real part of undefined is undefined let undefined: CircleF5E3 = zero / 0_i32; assert!(undefined.r().is_undefined());
/// ```
#[inline]
pub fn r(&self) -> Scalar<F, E> {
self.extract_component(self.real)
}
/// Returns the imaginary part of this Circle as a Scalar
///
/// # Description
///
/// Extracts the imaginary component of this Circle as a Scalar, preserving state information.
///
/// # Returns
///
/// - `[#,#]` ➔ `[#]` Imaginary component as a normal Scalar
/// - `[0]` ➔ `[0]` Zero
/// - `[↑]` ➔ `[↑]` Imaginary part as an exploded Scalar
/// - `[↓]` ➔ `[↓]` Imaginary part as a vanished Scalar
/// - `[∞]` ➔ `[∞]` Infinity
/// - `[℘?]` ➔ `[℘?]` The same undefined state
///
/// # Examples
///
/// ```rust
/// use spirix::{Circle, CircleF5E3, ScalarF5E3};
///
/// // Imaginary part of a normal complex number let complex = Circle::<i32, i8>::from((3_i32, 4_i32)); assert!(complex.i() == 4_i32);
///
/// // Imaginary part of Zero is Zero let zero = CircleF5E3::ZERO; assert!(zero.i().is_zero());
///
/// // Imaginary part of exploded preserves state let huge: CircleF5E3 = CircleF5E3::from((1_i32, ScalarF5E3::MAX * 2_i32)); assert!(huge.i().exploded());
///
/// // Imaginary part of undefined is undefined let undefined: CircleF5E3 = zero / 0_i32; assert!(undefined.i().is_undefined());
/// ```
#[inline]
pub fn i(&self) -> Scalar<F, E> {
self.extract_component(self.imaginary)
}
/// Returns true if this Circle is a normal complex number
///
/// # Description
///
/// Normal complex numbers have definite magnitudes and orientations and participate fully in all arithmetic operations. Unlike Zero or escaped values, normal complex numbers occupy the "standard" region of numeric space where arithmetic behaves conventionally.
///
/// # Returns
///
/// - `[#,#]` ➔ `true` Normal complex numbers
/// - `[0]` ➔ `false` Zero
/// - `[↑]` ➔ `false` Exploded values
/// - `[↓]` ➔ `false` Vanished values
/// - `[∞]` ➔ `false` Infinity
/// - `[℘?]` ➔ `false` Undefined states
///
/// # Examples
///
/// ```rust
/// use spirix::{Circle, CircleF4E4};
///
/// // Regular complex numbers are normal let normal = Circle::<i16, i16>::from((42_i16, 13_i16)); assert!(normal.is_normal());
///
/// // Normal values maintain their normality thru standard operations let still_normal: CircleF4E4 = CircleF4E4::from((42_i16, 13_i16)) * CircleF4E4::from((1_i16, 1_i16)) / 2_i16; assert!(still_normal.is_normal());
///
/// // Zero is not normal let zero = CircleF4E4::ZERO; assert!(!zero.is_normal());
///
/// // Exploded values are not normal let exploded = CircleF4E4::MAX * CircleF4E4::MAX; assert!(!exploded.is_normal());
///
/// // Vanished values are not normal let vanished: CircleF4E4 = CircleF4E4::MIN_POS / 45_i16; assert!(!vanished.is_normal());
///
/// // Undefined Circles are definitely not normal let undefined: CircleF4E4 = CircleF4E4::ONE / 0_i16; assert!(!undefined.is_normal());
///
/// // Operations that exceed representable range escape normality let no_longer_normal = CircleF4E4::MAX_NEG.square(); assert!(!no_longer_normal.is_normal());
/// ```
#[inline]
pub fn is_normal(&self) -> bool {
self.exponent != Self::ambiguous_exponent()
}
/// Checks if this Circle is in an undefined state `[℘?]`
///
/// # Description
///
/// Undefined states represent values from operations that have no known or agreed upon mathematical result. Spirix uses specific bit patterns to track various types of undefined states, maintaining "first cause" information.
///
/// # Returns
///
/// - `[℘?]` ➔ `true` Undefined states
/// - `[#,#]` ➔ `false` Normal complex numbers
/// - `[0]` ➔ `false` Zero
/// - `[↑]` ➔ `false` Exploded values
/// - `[↓]` ➔ `false` Vanished values
/// - `[∞]` ➔ `false` Infinity
///
/// # Examples
///
/// ```rust
/// use spirix::{Circle, CircleF5E3};
///
/// // Normal complex numbers are defined let normal = CircleF5E3::from((42_i32, 7_i32)); assert!(!normal.is_undefined());
///
/// // Infinity is defined let infinity: CircleF5E3 = normal / 0_i32; assert!(!infinity.is_undefined());
///
/// // Zero is defined let zero = CircleF5E3::ZERO; assert!(!zero.is_undefined());
///
/// // Escaped values are defined let exploded = CircleF5E3::MAX * CircleF5E3::MIN; assert!(!exploded.is_undefined());
///
/// // Exploded values in certain operations stay defined let still_defined: CircleF5E3 = exploded / 561_i32; assert!(!still_defined.is_undefined());
///
/// // But some operations produce undefined results let undefined_exploded_add: CircleF5E3 = still_defined + 1_i32; assert!(undefined_exploded_add.is_undefined());
/// ```
#[inline]
pub fn is_undefined(&self) -> bool {
// Not ambiguous? not undefined!
if self.exponent != Self::ambiguous_exponent() {
return false;
}
// The AMBIG partition is TOTAL: Zero, Infinity, N1 (exploded), N2 (vanished) — everything else is undefined, INCLUDING mismatched-prefix junk constructible via the pub fields. (The old version required matching component prefixes, leaving such patterns claiming no class at all.)
!self.is_zero() && !self.is_infinite() && !self.is_n1() && !self.is_n2()
}
#[doc(hidden)] // N-level internals, exposed for the FPGA test-vector tooling — not part of the stable API.
pub fn is_n0(&self) -> bool {
let prefix: i8 = self.real.sa();
let prefix_i: i8 = self.imaginary.sa();
if prefix != prefix_i {
return false;
}
prefix == prefix.rotate_right(1)
}
/// XOR fingerprint of both component prefixes: bit i of the result equals (prefix bit i) XOR (prefix bit i-1) for whichever component has that pair differing. Encodes both N-1 and N-2 class checks in one byte, avoiding the per-bit-pair branches the old version had. Unsigned shift to skip Rust's `i8 << 1` overflow check on prefix = i8::MIN.
#[inline]
fn class_xor(&self) -> u8 {
let pr: u8 = self.real.sa::<i8>() as u8;
let pi: u8 = self.imaginary.sa::<i8>() as u8;
(pr ^ (pr << 1)) | (pi ^ (pi << 1))
}
/// Canonicalize a fraction pair to N1 (min leading-same == 1) for the wide division pipelines.
/// Non-canonical normals (constructible via the pub fields) can be de-normalized enough that mag_sq >> FRAC vanishes and the fixed-point reciprocal panics on divide-by-zero; canonicalizing first also recovers the precision the products would otherwise lose.
/// Returns (real, imag, left_shift); a (0, 0) pair returns shift = -1 as the zero sentinel.
pub(crate) fn canonical_n1_pair(r: F, i: F) -> (F, F, isize) {
if r == F::zero() && i == F::zero() {
return (r, i, -1);
}
let ls = |x: F| -> isize {
let lz = x.leading_zeros() as isize;
let lo = (!x).leading_zeros() as isize;
lz.max(lo)
};
let lead = ls(r).min(ls(i));
let shift = lead - 1;
if shift <= 0 {
return (r, i, 0);
}
(r << shift, i << shift, shift)
}
#[doc(hidden)] // N-level internals, exposed for the FPGA test-vector tooling — not part of the stable API.
pub fn is_n1(&self) -> bool {
// N-1 pattern (top 2 = 01 or 10) ⇔ bit 7 of XOR set on either component ⇔ bit 7 set in OR.
self.class_xor() & 0x80 != 0
}
#[doc(hidden)] // N-level internals, exposed for the FPGA test-vector tooling — not part of the stable API.
pub fn is_n2(&self) -> bool {
// N-2 pattern (top 3 = 001 or 110) ⇔ XOR bit 7 clear AND XOR bit 6 set, on the component giving the result. OR across components: if either is N-1, its XOR bit 7 contaminates the OR and the `== 0x40` check fails — exactly the "either N-1 ⇒ not N-2" precedence the old branchy version enforced.
(self.class_xor() & 0xC0) == 0x40
}
/// Returns true if this Circle's magnitude is negligible `[0]`, `[↓]`
///
/// # Description
///
/// Negligible values have effectively zero magnitude. This includes both actual Zero and vanished values that have become so small they no longer meaningfully contribute to addition or subtraction operations.
///
/// # Returns
///
/// - `[0]` ➔ `true` Zero
/// - `[↓]` ➔ `true` Vanished values
/// - `[#,#]` ➔ `false` Normal complex numbers
/// - `[↑]` ➔ `false` Exploded values
/// - `[∞]` ➔ `false` Infinity
/// - `[℘?]` ➔ `false` Undefined states
///
/// # Examples
///
/// ```rust
/// use spirix::{Circle, CircleF4E5};
///
/// // Zero: The original negligible number let zero = Circle::<i16, i32>::ZERO; assert!(zero.is_negligible());
///
/// // A Circle so small it's effectively zero let vanished: CircleF4E5 = CircleF4E5::MIN_POS / 57_i16; assert!(vanished.is_negligible());
///
/// // Normal values are not negligible let normal = CircleF4E5::from((1729_i16, -104_i16)); assert!(!normal.is_negligible());
///
/// // Exploded values are not negligible let huge = CircleF4E5::MAX * CircleF4E5::MIN; assert!(!huge.is_negligible());
///
/// // Infinity is not negligible let infinity: CircleF4E5 = CircleF4E5::ONE / 0_i16; assert!(!infinity.is_negligible());
///
/// // Undefined Circles are not negligible let undefined: CircleF4E5 = CircleF4E5::ZERO / 0_i16; assert!(!undefined.is_negligible());
/// ```
#[inline]
pub fn is_negligible(&self) -> bool {
// Negligible = Zero or Vanished; both require the AMBIG exponent (see vanished()).
self.is_zero() || self.vanished()
}
/// Returns true if this Circle is an infinitesimal value `[↓]` but not Zero `[0]`
///
/// # Description
///
/// Vanished values are Circles that have become so small their magnitude is effectively zero, but they retain their orientation information. They participate in multiplication and division operations, but are treated as Zero in addition and subtraction.
///
/// # Returns
///
/// - `[↓]` ➔ `true` Vanished values
/// - `[0]` ➔ `false` Zero
/// - `[#,#]` ➔ `false` Normal complex numbers
/// - `[↑]` ➔ `false` Exploded values
/// - `[∞]` ➔ `false` Infinity
/// - `[℘?]` ➔ `false` Undefined states
///
/// # Examples
///
/// ```rust
/// use spirix::{Circle, CircleF4E3, Scalar, ScalarF4E3};
///
/// // Create a ridiculously small Circle let vanished = Circle::<i16, i8>::MIN_POS.pow(Scalar::<i16, i8>::MAX); assert!(vanished.vanished());
///
/// // Actual Zero is not vanished - it's truly Zero let actual_zero = CircleF4E3::ZERO; assert!(!actual_zero.vanished());
///
/// // Normal values are not vanished let normal = CircleF4E3::from((42_i16, -1_i16)); assert!(!normal.vanished());
///
/// // Large escaped values aren't vanished - they're exploded! let ginormous = CircleF4E3::MAX.pow(ScalarF4E3::MAX); assert!(!ginormous.vanished()); assert!(ginormous.exploded());
///
/// // Division by a vanished value produces an exploded result let exploded: CircleF4E3 = 1_i16 / vanished; assert!(exploded.exploded()); assert!(!exploded.vanished());
/// ```
#[inline]
pub fn vanished(&self) -> bool {
// Class shapes only mean escape at the AMBIG exponent — a normal-exponent value whose fraction pair happens to be N2-shaped (non-canonical normal) is NOT vanished. Mirrors exploded()'s gate.
if !self.is_normal() {
return self.is_n2();
}
false
}
/// Alias for [`Self::vanished`] — matches the `is_*` predicate family and the Scalar API.
#[inline]
pub fn is_vanished(&self) -> bool {
self.vanished()
}
/// Alias for [`Self::exploded`] — matches the `is_*` predicate family and the Scalar API.
#[inline]
pub fn is_exploded(&self) -> bool {
self.exploded()
}
/// Returns true if this Circle is ridiculously large `[↑]` but not infinity `[∞]`
///
/// # Description
///
/// Exploded values are Circles that have grown so large their magnitude can no longer be recorded, but they maintain their orientation information. They participate meaningfully in multiplication and division operations, but addition and subtraction with normal numbers will produce undefined results.
///
/// # Returns
///
/// - `[↑]` ➔ `true` Exploded values
/// - `[0]` ➔ `false` Zero
/// - `[#,#]` ➔ `false` Normal complex numbers
/// - `[↓]` ➔ `false` Vanished values
/// - `[∞]` ➔ `false` Infinity
/// - `[℘?]` ➔ `false` Undefined states
///
/// # Examples
///
/// ```rust
/// use spirix::{Circle, CircleF7E7};
///
/// // Create a really big Circle let gigantic = Circle::<i128, i128>::MAX.square(); assert!(gigantic.exploded());
///
/// // Actual Zero is not exploded let actual_zero = CircleF7E7::ZERO; assert!(!actual_zero.exploded());
///
/// // Normal values are not exploded let normal = CircleF7E7::from((42_i128, 13_i128)); assert!(!normal.exploded());
///
/// // Small escaped values aren't exploded - they're vanished! let tiny: CircleF7E7 = CircleF7E7::MIN_POS / 12_i128; assert!(!tiny.exploded()); assert!(tiny.vanished());
///
/// // Infinity is not exploded - it's a distinct state let infinity: CircleF7E7 = 1_i128 / actual_zero; assert!(!infinity.exploded()); assert!(infinity.is_infinite());
///
/// // Multiplying or dividing exploded stays exploded let still_exploded: CircleF7E7 = gigantic * 7_i128; assert!(still_exploded.exploded()); let also_exploded: CircleF7E7 = gigantic / 7_i128; assert!(also_exploded.exploded());
///
/// // Division by vanished produces exploded let also_exploded = CircleF7E7::ONE / tiny; assert!(also_exploded.exploded());
/// ```
#[inline]
pub fn exploded(&self) -> bool {
if !self.is_normal() {
return self.is_n1();
}
false
}
/// Returns true if this Circle is beyond normal magnitude `[↑]` or `[∞]`
///
/// # Description
///
/// Transfinite values are complex numbers that have grown beyond representable magnitude. This includes both directional exploded values `[↑]` that maintain orientation information, and mathematical infinity `[∞]` which represents a singularity, like division by zero.
///
/// # Returns
///
/// - `[↑]` ➔ `true` Exploded values
/// - `[∞]` ➔ `true` Infinity
/// - `[0]` ➔ `false` Zero
/// - `[#,#]` ➔ `false` Normal complex numbers
/// - `[↓]` ➔ `false` Vanished values
/// - `[℘?]` ➔ `false` Undefined states
///
/// # Examples
///
/// ```rust
/// use spirix::{Circle, CircleF5E4};
///
/// // Exploded Circle is transfinite let exploded = CircleF5E4::MAX * CircleF5E4::MAX; assert!(exploded.is_transfinite()); assert!(exploded.exploded()); // But it's not infinity
///
/// // Division by zero produces true mathematical infinity let infinity: CircleF5E4 = CircleF5E4::ONE / 0_i32; assert!(infinity.is_transfinite()); assert!(infinity.is_infinite()); assert!(!infinity.exploded()); // Not the same as exploded
///
/// // Normal complex values are not transfinite let normal = CircleF5E4::from((42_i32, 13_i32)); assert!(!normal.is_transfinite());
///
/// // Zero is not transfinite let zero = CircleF5E4::ZERO; assert!(!zero.is_transfinite());
///
/// // Vanished values are not transfinite (they're the opposite!) let tiny: CircleF5E4 = CircleF5E4::MIN_POS / 1234_i32; assert!(!tiny.is_transfinite());
///
/// // The reciprocal of transfinite is negligible let reciprocal = CircleF5E4::ONE / exploded; assert!(!reciprocal.is_transfinite()); assert!(reciprocal.is_negligible());
///
/// // Math operations with infinity follow mathematical rules let also_infinity = infinity * CircleF5E4::PI; assert!(also_infinity.is_transfinite()); assert!(also_infinity.is_infinite());
///
/// // Adding infinity to a finite value stays infinite let still_inf = infinity + CircleF5E4::from((1000_i32, 500_i32)); assert!(still_inf.is_transfinite());
/// ```
#[inline]
pub fn is_transfinite(&self) -> bool {
if !self.is_normal() {
return self.is_n1() || (self.real == (-F::one()) && self.imaginary == (-F::one()));
}
false
}
/// Returns true if this Circle represents a finite complex number `[0]`, `[#,#]`
///
/// # Description
///
/// Finite Circles have known magnitudes and orientations and can participate fully in all arithmetic operations. This includes all normal complex numbers and Zero, but excludes escaped values (exploded and vanished) and undefined states.
///
/// # Returns
///
/// - `[0]` ➔ `true` Zero
/// - `[#,#]` ➔ `true` Normal complex numbers
/// - `[↑]` ➔ `false` Exploded values
/// - `[↓]` ➔ `false` Vanished values
/// - `[∞]` ➔ `false` Infinity
/// - `[℘?]` ➔ `false` Undefined states
///
/// # Examples
///
/// ```rust
/// use spirix::{Circle, CircleF5E4};
///
/// // Normal values are finite let normal = Circle::<i32, i16>::from((42_i32, 2_i32)); assert!(normal.is_finite());
///
/// // Zero is finite let zero = CircleF5E4::ZERO; assert!(zero.is_finite());
///
/// // Complex number with i is finite let complex = CircleF5E4::POS_I; assert!(complex.is_finite());
///
/// // Exploded values are not finite let huge: CircleF5E4 = CircleF5E4::MAX * 2_i32; assert!(!huge.is_finite());
///
/// // Vanished values are not finite let tiny: CircleF5E4 = CircleF5E4::MIN_POS / 28_i32; assert!(!tiny.is_finite());
///
/// // Infinity is not finite let infinity: CircleF5E4 = CircleF5E4::ONE / 0_i32; assert!(!infinity.is_finite());
///
/// // Undefined Circles are not finite let undefined: CircleF5E4 = CircleF5E4::ZERO / 0_i32; assert!(!undefined.is_finite());
///
/// // Operations that produce normal results usually return finite values let still_finite: CircleF5E4 = CircleF5E4::from((42_i32, 2_i32)) + CircleF5E4::ONE; assert!(still_finite.is_finite());
///
/// // Operations that exceed representable range escape finiteness let no_longer_finite: CircleF5E4 = CircleF5E4::MAX + CircleF5E4::MAX / 2_i32; assert!(!no_longer_finite.is_finite());
/// ```
#[inline]
pub fn is_finite(&self) -> bool {
self.is_normal() || self.is_zero()
}
/// Returns true if this Circle is the true origin point `[0]`
///
/// # Description
///
/// Zero represents the absence of magnitude in Spirix. Unlike vanished values which approach but never equal Zero, this is the genuine, mathematical Zero that serves as the additive identity.
///
/// # Returns
///
/// - `[0]` ➔ `true` Zero
/// - `[#,#]` ➔ `false` Normal complex numbers
/// - `[↑]` ➔ `false` Exploded values
/// - `[↓]` ➔ `false` Vanished values
/// - `[∞]` ➔ `false` Infinity
/// - `[℘?]` ➔ `false` Undefined states
///
/// # Examples
///
/// ```rust
/// use spirix::{Circle, CircleF6E4};
///
/// // The one and only Zero
/// let zero = Circle::<i64, i16>::ZERO; assert!(zero.is_zero());
///
/// // Even a very small Circle is not Zero — it's vanished, not Zero
/// let tiny: CircleF6E4 = CircleF6E4::MIN_POS / 61_i64; assert!(!tiny.is_zero()); assert!(tiny.vanished());
///
/// // Normal values are not Zero
/// let normal = CircleF6E4::from((42_i64, 17_i64)); assert!(!normal.is_zero());
///
/// // Exploded values are not Zero
/// let huge = CircleF6E4::MAX * CircleF6E4::MAX; assert!(!huge.is_zero());
///
/// // Infinity is not Zero
/// let infinity: CircleF6E4 = CircleF6E4::ONE / 0_i64; assert!(!infinity.is_zero());
///
/// // Undefined states aren't Zero
/// let undefined: CircleF6E4 = CircleF6E4::ZERO / 0_i64; assert!(!undefined.is_zero());
///
/// // Mathematical operations with Zero behave as expected
/// let still_zero = zero * CircleF6E4::from((3_i64, 4_i64)); assert!(still_zero.is_zero());
///
/// let normal_again = still_zero + CircleF6E4::from((163_i64, -16_i64)); assert!(!normal_again.is_zero()); assert!(normal_again.is_normal());
/// ```
#[inline]
pub fn is_zero(&self) -> bool {
// Zero lives at the AMBIG exponent — a normal-exponent value whose prefixes happen to be zero (pub-field-constructible) is a (degenerate) normal, not Zero.
if self.exponent != Self::ambiguous_exponent() {
return false;
}
let prefix_r: i8 = self.real.sa();
let prefix_i: i8 = self.imaginary.sa();
prefix_r == 0 && prefix_i == 0
}
/// Returns true if this Circle represents mathematical infinity `[∞]`
///
/// # Description
///
/// Infinity represents the result of operations like division by zero or other mathematical concepts that produce a singularity. In Spirix, this corresponds to the "point at infinity" on the Riemann sphere, a single entity that represents the limit of all approaches to infinity.
///
/// # Returns
///
/// - `[∞]` ➔ `true` Infinity
/// - `[0]` ➔ `false` Zero
/// - `[#,#]` ➔ `false` Normal complex numbers
/// - `[↑]` ➔ `false` Exploded values
/// - `[↓]` ➔ `false` Vanished values
/// - `[℘?]` ➔ `false` Undefined states
///
/// # Examples
///
/// ```rust
/// use spirix::{Circle, CircleF5E4};
///
/// // Division by zero produces infinity let infinity: CircleF5E4 = CircleF5E4::ONE / 0_i32; assert!(infinity.is_infinite());
///
/// // Exploded values are not infinity let exploded = CircleF5E4::MAX * CircleF5E4::MAX; assert!(!exploded.is_infinite()); assert!(exploded.exploded());
///
/// // Normal values are not infinity let normal = CircleF5E4::from((42_i32, 7_i32)); assert!(!normal.is_infinite());
///
/// // Zero is not infinity let zero = CircleF5E4::ZERO; assert!(!zero.is_infinite());
///
/// // Undefined values are not infinity let undefined: CircleF5E4 = CircleF5E4::ZERO / 0_i32; assert!(!undefined.is_infinite());
///
/// // Operations with infinity follow mathematical rules let still_infinity = infinity * CircleF5E4::from((3_i32, -4_i32)); assert!(still_infinity.is_infinite());
///
/// // Infinity times zero produces undefined let also_undefined: CircleF5E4 = infinity * CircleF5E4::ZERO; assert!(also_undefined.is_undefined());
/// ```
#[inline]
pub fn is_infinite(&self) -> bool {
// Infinity lives at the AMBIG exponent (see is_zero for the same gate rationale).
if self.exponent != Self::ambiguous_exponent() {
return false;
}
let prefix_r: i8 = self.real.sa();
let prefix_i: i8 = self.imaginary.sa();
prefix_r == -1 && prefix_i == -1
}
/// Negates both real and imaginary components in place (a+bi → -a-bi). Escaped values preserve their escape state; zero, infinity, and undefined are unchanged.
pub(crate) fn circle_negate(&mut self) {
if self.exponent != Self::ambiguous_exponent() {
let one: E = 1u8.as_();
if self.real == Self::neg_one_normal() {
self.real = Self::pos_one_normal();
self.imaginary = (self.imaginary >> 1isize).wrapping_neg();
self.exponent = self.exponent.wrapping_add(&one);
return;
} else if self.imaginary == Self::neg_one_normal() {
self.imaginary = Self::pos_one_normal();
self.real = (self.real >> 1isize).wrapping_neg();
self.exponent = self.exponent.wrapping_add(&one);
return;
}
self.real = self.real.wrapping_neg();
self.imaginary = self.imaginary.wrapping_neg();
self.normalize();
} else {
// Extract high byte and cast
let prefix: i8 = self.real.sa();
let prefix_i: i8 = self.imaginary.sa();
if prefix == prefix_i {
// Test for undefined, Zero and Infinity Check if top 3 bits are equal by pushing 5 bits off ↓↓↓ ↓↓↓ □□□xxxxx -5-> □□□□□□□□ - Undefined (℘)
let top_three = prefix >> 5;
// Then rotate and compare. If uniform, they will be equal True for undefined, Zero and Infinity
if top_three == top_three.rotate_right(1) {
return;
}
}
if self.vanished() {
self.real = self.real.wrapping_neg();
self.imaginary = self.imaginary.wrapping_neg();
self.normalize_vanished();
} else {
if self.real == Self::neg_one_normal() {
self.real = Self::pos_one_normal();
self.imaginary = (self.imaginary >> 1isize).wrapping_neg();
} else if self.imaginary == Self::neg_one_normal() {
self.imaginary = Self::pos_one_normal();
self.real = (self.real >> 1isize).wrapping_neg();
} else {
self.real = self.real.wrapping_neg();
self.imaginary = self.imaginary.wrapping_neg();
self.normalize_exploded()
}
}
}
}
/// Returns the complex conjugate of this Circle
///
/// # Description
///
/// Computes the complex conjugate by negating the imaginary component, while preserving the real component. For a complex number a + b*i, the conjugate is a - b*i.
///
/// # Returns
///
/// - `[#,#]` ➔ `[#,#]` Complex conjugate
/// - `[↑]` ➔ `[↑]` Conjugate with exploded state
/// - `[↓]` ➔ `[↓]` Conjugate with vanished state
/// - `[0]` ➔ `[0]` Zero unchanged
/// - `[∞]` ➔ `[∞]` Infinity unchanged
/// - `[℘?]` ➔ `[℘?]` Same undefined state
///
/// # Examples
///
/// ```rust
/// use spirix::{Circle, CircleF5E3};
///
/// // Conjugate of a standard complex number let complex = Circle::<i32, i8>::from((3_i32, 4_i32)); let conj = complex.conjugate(); assert!(conj.r() == 3_i32); assert!(conj.i() == -4_i32); assert!(complex.magnitude() == conj.magnitude());
///
/// // Conjugate of a pure real number doesn't change it let real = CircleF5E3::from((42_i32, 0_i32)); assert!(real.conjugate() == real);
///
/// // Conjugate of a pure imaginary number negates it let imag = CircleF5E3::from((0_i32, 7_i32)); assert!(imag.conjugate().i() == -7_i32);
///
/// // Conjugate of Zero is Zero let zero = CircleF5E3::ZERO; assert!(zero.conjugate() == zero);
///
/// // Conjugate of Infinity is Infinity let infinity: CircleF5E3 = CircleF5E3::ONE / 0_i32; assert!(infinity.conjugate().is_infinite());
///
/// // Conjugate of vanished value preserves vanished state let tiny: CircleF5E3 = CircleF5E3::MIN_POS / 42_i32; assert!(tiny.conjugate().vanished());
///
/// // Conjugate of undefined remains undefined let undefined: CircleF5E3 = CircleF5E3::ZERO / 0_i32; assert!(undefined.conjugate().is_undefined());
/// ```
pub fn conjugate(&self) -> Circle<F, E> {
if self.is_normal() {
if self.imaginary == Self::neg_one_normal() {
return Circle {
real: self.real >> 1isize,
imaginary: Self::pos_one_normal(),
exponent: self.exponent.wrapping_add(&E::one()),
};
}
let mut conjugate = Circle {
real: self.real,
imaginary: self.imaginary.wrapping_neg(),
exponent: self.exponent,
};
conjugate.normalize();
conjugate
} else if self.vanished() {
let mut conjugate = Circle {
real: self.real,
imaginary: self.imaginary.wrapping_neg(),
exponent: self.exponent,
};
conjugate.normalize_vanished();
conjugate
} else if self.exploded() {
if self.imaginary == Self::neg_one_normal() {
return Circle {
real: (self.real >> 1isize).wrapping_neg(),
imaginary: Self::pos_one_normal(),
exponent: self.exponent,
};
} else {
let mut conjugate = Circle {
real: self.real,
imaginary: self.imaginary.wrapping_neg(),
exponent: self.exponent,
};
conjugate.normalize_exploded();
conjugate
}
} else {
*self
}
}
/// Computes the complex conjugate of this Circle in place
///
/// # Description
///
/// Performs an in-place computation of the complex conjugate by negating the imaginary component, while preserving the real component. For a complex number a + b*i, the conjugate is a - b*i.
///
/// # Effects
///
/// - `[#,#]` ➔ `[#,#]` Negates imaginary part, preserves real
/// - `[↑]` ➔ `[↑]` Preserves escape state while flipping orientation
/// - `[↓]` ➔ `[↓]` Preserves escape state while flipping orientation
/// - `[0]` ➔ `[0]` Zero unchanged
/// - `[∞]` ➔ `[∞]` Infinity unchanged
/// - `[℘?]` ➔ `[℘?]` Same undefined state
///
/// # Examples
///
/// ```rust
/// use spirix::{Circle, CircleF5E3};
///
/// // Conjugate of a standard complex number let mut complex = Circle::<i32, i8>::from((3_i32, 4_i32)); let magnitude = complex.magnitude(); complex.conjugate_mut(); assert!(complex.r() == 3_i32); assert!(complex.i() == -4_i32); assert!(complex.magnitude() == magnitude);
///
/// // Conjugate of a pure real number doesn't change it let mut real = CircleF5E3::from((42_i32, 0_i32)); let original = real; real.conjugate_mut(); assert!(real == original);
///
/// // Conjugate of a pure imaginary number negates it let mut imag = CircleF5E3::from((0_i32, 7_i32)); imag.conjugate_mut(); assert!(imag.i() == -7_i32);
///
/// // Conjugate of Zero is Zero let mut zero = CircleF5E3::ZERO; zero.conjugate_mut(); assert!(zero.is_zero());
///
/// // Conjugate of Infinity remains Infinity let mut infinity: CircleF5E3 = CircleF5E3::ONE / 0_i32; infinity.conjugate_mut(); assert!(infinity.is_infinite());
///
/// // Conjugate of vanished value preserves vanished state let mut tiny: CircleF5E3 = CircleF5E3::MIN_POS / 42_i32; tiny.conjugate_mut(); assert!(tiny.vanished());
///
/// // Conjugate of undefined remains undefined let mut undefined: CircleF5E3 = CircleF5E3::ZERO / 0_i32; undefined.conjugate_mut(); assert!(undefined.is_undefined());
/// ```
pub fn conjugate_mut(&mut self) {
if self.is_normal() {
if self.imaginary == Self::neg_one_normal() {
self.real = self.real >> 1isize;
self.imaginary = Self::pos_one_normal();
self.exponent = self.exponent.wrapping_add(&E::one());
return;
}
self.imaginary = self.imaginary.wrapping_neg();
self.normalize()
} else if self.vanished() {
self.imaginary = self.imaginary.wrapping_neg();
self.normalize_vanished();
} else if self.exploded() {
if self.imaginary == Self::neg_one_normal() {
self.imaginary = Self::pos_one_normal();
self.real = (self.real >> 1isize).wrapping_neg();
} else {
self.imaginary = self.imaginary.wrapping_neg();
self.normalize_exploded()
}
}
}
/// Returns the magnitude of this Circle
///
/// # Description
///
/// Computes the magnitude of this Circle as a Scalar. For a complex number a + b*i, the magnitude is √(a² + b²).
///
/// # Returns
///
/// - `[#,#]` ➔ `[+#]` Scalar representing distance from origin
/// - `[↑]` ➔ `[↑]` Scalar with exploded state
/// - `[↓]` ➔ `[↓]` Scalar with vanished state
/// - `[0]` ➔ `[0]` Zero unchanged
/// - `[∞]` ➔ `[∞]` Infinity unchanged
/// - `[℘?]` ➔ `[℘?]` Scalar with same undefined state
///
/// # Examples
///
/// ```rust
/// use spirix::{Circle, CircleF4E4, ScalarF4E4};
///
/// // Magnitude of a standard 3-4-5 triangle let complex = Circle::<i16, i16>::from((3_i16, 4_i16)); assert!(complex.magnitude() == 5_i16);
///
/// // Magnitude of a pure real number is its absolute value let real = CircleF4E4::from((-42_i16, 0_i16)); assert!(real.magnitude() == 42_i16);
///
/// // Magnitude of a pure imaginary number is its absolute value let imag = CircleF4E4::from((0_i16, -7_i16)); assert!(imag.magnitude() == 7_i16);
///
/// // Magnitude of Zero is Zero let zero = CircleF4E4::ZERO; assert!(zero.magnitude() == ScalarF4E4::ZERO);
///
/// // Magnitude of Infinity is Infinity let infinity: CircleF4E4 = CircleF4E4::ONE / 0_i16; assert!(infinity.magnitude().is_infinite());
///
/// // Magnitude of undefined is undefined let undefined: CircleF4E4 = CircleF4E4::ZERO / 0_i16; assert!(undefined.magnitude().is_undefined());
/// ```
pub fn magnitude(&self) -> Scalar<F, E> {
let magnitude_squared = self.magnitude_squared();
magnitude_squared.sqrt()
}
/// Returns the square of the magnitude of this Circle
///
/// # Description
///
/// Computes the squared magnitude of this Circle as a Scalar, avoiding the square root operation. For a complex number a + b*i, the squared magnitude is a * a + b * b.
///
/// # Returns
///
/// - `[#,#]` ➔ `[+#]` Scalar representing squared distance from origin
/// - `[↑]` ➔ `[↑]` Scalar with exploded state
/// - `[↓]` ➔ `[↓]` Scalar with vanished state
/// - `[0]` ➔ `[0]` Zero unchanged
/// - `[∞]` ➔ `[∞]` Infinity unchanged
/// - `[℘?]` ➔ `[℘?]` Scalar with same undefined state
///
/// # Examples
///
/// ```rust
/// use spirix::{Circle, CircleF6E3, ScalarF6E3};
///
/// // Squared magnitude of a standard 3-4-5 triangle let complex = Circle::<i64, i8>::from((3_i64, 4_i64)); assert!(complex.magnitude_squared() == 25_i64);
///
/// // Squared magnitude of a pure real number let real = CircleF6E3::from((4_i64, 0_i64)); assert!(real.magnitude_squared() == 16_i64);
///
/// // Squared magnitude of a pure imaginary number let imag = CircleF6E3::from((0_i64, 5_i64)); assert!(imag.magnitude_squared() == 25_i64);
///
/// // Squared magnitude of Zero is Zero let zero = CircleF6E3::ZERO; assert!(zero.magnitude_squared() == ScalarF6E3::ZERO);
///
/// // Squared magnitude of Infinity is Infinity let infinity: CircleF6E3 = CircleF6E3::ONE / 0_i64; assert!(infinity.magnitude_squared().is_infinite());
///
/// // Squared magnitude of undefined is undefined let undefined: CircleF6E3 = CircleF6E3::ZERO / 0_i64; assert!(undefined.magnitude_squared().is_undefined());
/// ```
pub fn magnitude_squared(&self) -> Scalar<F, E> {
let real_squared = self.r().square();
let imaginary_squared = self.i().square();
real_squared + imaginary_squared
}
/// Returns the reciprocal (multiplicative inverse) of this Circle
///
/// # Description
///
/// Computes the reciprocal 1/z of this Circle. For a complex number a + b*i, the reciprocal is (a - b*i)/(a² + b²), which equals conjugate(z) / |z|².
///
/// # Returns
///
/// - `[#,#]` ➔ `[#,#]` Reciprocal with same precision
/// - `[↑]` ➔ `[↓]` Large values become small (exploded → vanished)
/// - `[↓]` ➔ `[↑]` Small values become large (vanished → exploded)
/// - `[0]` ➔ `[∞]` Zero becomes Infinity
/// - `[∞]` ➔ `[0]` Infinity becomes Zero
/// - `[℘?]` ➔ `[℘?]` Same undefined state
///
/// # Examples
///
/// ```rust
/// use spirix::{Circle, CircleF5E3};
///
/// // Reciprocal of a real number let real = Circle::<i32, i8>::from(4_i32); let recip = real.reciprocal(); assert!(recip.r() == 0.25_f32); assert!(recip.i() == 0_i32);
///
/// // Reciprocal of a pure imaginary number let imag = CircleF5E3::from((0_i32, 2_i32)); let recip_imag = imag.reciprocal(); assert!(recip_imag.r() == 0_i32); assert!(recip_imag.i() == -0.5_f32);
///
/// // Reciprocal of a general complex number let complex = CircleF5E3::from((3_i32, 4_i32)); let recip_complex = complex.reciprocal(); assert!((recip_complex.r() - 0.12_f32).magnitude() < 0.01_f32); assert!((recip_complex.i() + 0.16_f32).magnitude() < 0.01_f32);
///
/// // Reciprocal relationships let z = CircleF5E3::from((1_i32, 1_i32)); let recip_z = z.reciprocal(); assert!((z * recip_z - CircleF5E3::ONE).magnitude() < 0.01_f32);
///
/// // Reciprocal of Zero is Infinity let zero = CircleF5E3::ZERO; assert!(zero.reciprocal().is_infinite());
///
/// // Reciprocal of Infinity is Zero let infinity: CircleF5E3 = CircleF5E3::ONE / 0_i32; assert!(infinity.reciprocal().is_zero());
///
/// // Reciprocal of undefined remains undefined let undefined: CircleF5E3 = CircleF5E3::ZERO / 0_i32; assert!(undefined.reciprocal().is_undefined());
/// ```
pub fn reciprocal(&self) -> Circle<F, E> {
1 / self
}
/// Returns the normalized unit vector form of this Circle
///
/// # Description
///
/// Creates a unit Circle (magnitude 1) pointing in the same direction as this Circle. This preserves the orientation while normalizing the magnitude, by dividing the Circle by its magnitude.
///
/// # Returns
///
/// - `[#,#]` ➔ `[#,#]` Unit Circle with same orientation
/// - `[↑]` ➔ `[#,#]` Normal unit Circle with same orientation (escape state removed)
/// - `[↓]` ➔ `[#,#]` Normal unit Circle with same orientation (escape state removed)
/// - `[0]` ➔ `[℘±∅]` Undefined value with SIGN_INDETERMINATE pattern
/// - `[∞]` ➔ `[℘±∅]` Undefined value with SIGN_INDETERMINATE pattern
/// - `[℘?]` ➔ `[℘?]` Same undefined state
///
/// # Examples
///
/// ```rust
/// use spirix::{Circle, CircleF5E5};
///
/// // Normalizing a standard complex number let complex = Circle::<i32, i32>::from((-3_i32, 0_i32)); let unit = complex.sign(); assert!(unit.r() == -1_i32); assert!(unit.i() == 0_i32);
///
/// // Normalizing a complex number with both components let z = CircleF5E5::from((1_i32, 1_i32)); let unit_z = z.sign(); assert!(unit_z.magnitude() == 1_i32);
///
/// // Normalizing a pure real number let real = CircleF5E5::from((42_i32, 0_i32)); assert!(real.sign().r() == 1_i32); assert!(real.sign().i() == 0_i32);
///
/// // Normalizing a pure imaginary number let imag = CircleF5E5::from((0_i32, 7_i32)); assert!(imag.sign().r() == 0_i32); assert!(imag.sign().i() == 1_i32);
///
/// // Normalizing an exploded value removes the escape state let huge: CircleF5E5 = CircleF5E5::MAX * 2_i32; assert!(huge.exploded()); assert!(!huge.sign().exploded());
///
/// // Zero has no orientation to normalize let zero = CircleF5E5::ZERO; assert!(zero.sign().is_undefined());
///
/// // Infinity's direction is undefined let infinity: CircleF5E5 = CircleF5E5::ONE / 0_i32; assert!(infinity.sign().is_undefined());
/// ```
pub fn sign(&self) -> Circle<F, E> {
if self.exponent == Self::ambiguous_exponent() {
let prefix_r: i8 = self.real.sa();
let prefix_i: i8 = self.imaginary.sa();
if prefix_r == prefix_i {
if prefix_r == prefix_r.rotate_right(1) {
// Zero and Infinity check
let prefix: F = SIGN_INDETERMINATE.prefix.sa();
return Self {
real: prefix,
imaginary: prefix,
exponent: Self::ambiguous_exponent(),
};
}
let top_three = prefix_r >> 5;
// Undefined check
if top_three == top_three.rotate_right(1) {
return *self;
}
}
}
// Use binade_origin (+1.0 binade) as the exponent reference for the dividend so that result / |result| lands a unit-magnitude Circle. The earlier `E::zero()` predated AMBIG=0 — under the new encoding zero IS the AMBIG sentinel, so it poisoned the divisor and the division returned NaN.
let result = Circle {
real: self.real,
imaginary: self.imaginary,
exponent: Self::binade_origin(),
};
return result / result.magnitude();
}
/// Normalizes this Scalar by shifting the fraction left until the most significant bit is in the N-1 position, adjusting the exponent accordingly. Sign is placed in N-0.
///
/// If shifting would cause a small number to vanish, marks the number as ambiguous and normalizes it to N-2.
///
/// 01234567...
///
/// □■xxxxxx... - Normal positive numbers
///
/// ■□xxxxxx... - Normal negative numbers
///
/// - Normalizes all scalars!
pub(crate) fn normalize(&mut self) {
let shift_r = self.real.leading_ones().max(self.real.leading_zeros());
let shift_i = self
.imaginary
.leading_ones()
.max(self.imaginary.leading_zeros());
let shift = shift_r.min(shift_i);
if shift > 1 {
let shift = shift as isize;
let s: E = if shift == Self::fraction_bits() {
if !self.real.is_negative() && !self.imaginary.is_negative() {
self.exponent = Self::ambiguous_exponent();
return;
}
shift.wrapping_add(1).as_()
} else {
shift.as_()
};
// AMBIG=0 underflow: cycle-widen + w_sub, check against min_pos (= 1). Crossing below means we wrapped past AMBIG and the result is in the vanished region.
let pa = self.exponent.cycle_widen();
let w_s = s.cycle_widen();
let new_pos = pa.w_sub(w_s);
let min_pos = Self::min_exponent().cycle_widen();
if new_pos < min_pos {
self.exponent = Self::ambiguous_exponent();
self.real = self.real << shift.wrapping_sub(2);
self.imaginary = self.imaginary << shift.wrapping_sub(2);
} else {
// The +1 absorbs the canonical N1 leading bit back into the exponent (net: fraction shifts left by shift-1, exp drops by shift-1).
self.exponent = new_pos.deflate().wrapping_add(&E::one());
self.real = self.real << shift.wrapping_sub(1);
self.imaginary = self.imaginary << shift.wrapping_sub(1);
}
}
}
/// Normalizes a vanished Scalar by shifting its fraction to the N-2 position. Sign bits occupy N-0 and N-1, exponent is not touched
///
/// Example bit positions: 01234567... □□■xxxxx... - Vanished positive numbers ■■□xxxxx... - Vanished negative numbers
pub(crate) fn normalize_vanished(&mut self) {
let shift_r = self.real.leading_ones().max(self.real.leading_zeros());
let shift_i = self
.imaginary
.leading_ones()
.max(self.imaginary.leading_zeros());
let shift: isize = shift_r.min(shift_i).as_();
if shift > 2 {
self.real = self.real << shift.wrapping_sub(2);
self.imaginary = self.imaginary << shift.wrapping_sub(2);
} else if shift < 2 {
self.real = self.real >> 2isize.wrapping_sub(shift);
self.imaginary = self.imaginary >> 2isize.wrapping_sub(shift);
}
}
/// Normalizes an exploded Scalar by shifting the fraction left until the most significant bit is in the N-1 position, exponent is not touched.
///
/// Example bit positions: 01234567... □■xxxxxx... - Exploded positive numbers ■□xxxxxx... - Exploded negative numbers
pub(crate) fn normalize_exploded(&mut self) {
let shift_r = self.real.leading_ones().max(self.real.leading_zeros());
let shift_i = self
.imaginary
.leading_ones()
.max(self.imaginary.leading_zeros());
let shift = shift_r.min(shift_i);
if shift > 1 {
let shift = shift as isize;
self.real = self.real << shift.wrapping_sub(1);
self.imaginary = self.imaginary << shift.wrapping_sub(1);
}
}
}