simplify unit vector impl

Author: NailxSharipov

src/int/angle/angle.rs

@@ -80,8 +80,9 @@ impl Angle {
     /// opposite rays return exactly `2^31`. A nonzero cross product is never
     /// rounded to an empty arc, even arbitrarily close to a full turn.
     /// Products fit in the associated wide type, including `i128` for `i64`:
-    /// each component is at most S = 2^(I::BITS-2), each product at most S²,
-    /// and sums/differences at most 2S². No products of cross/dot are formed.
+    /// components are approximately bounded by S = 2^(I::BITS-2), so products
+    /// and sums/differences fit with room for float rounding near unit length.
+    /// No products of cross/dot are formed.
     pub fn between<I: IntNumber>(from: UnitIntVector<I>, to: UnitIntVector<I>) -> Self {
         let (ax, ay) = (from.x().to_wide(), from.y().to_wide());
         let (bx, by) = (to.x().to_wide(), to.y().to_wide());

src/int/angle/rotation.rs

@@ -109,13 +109,14 @@ impl<I: IntNumber> Rotation<I> {
     }
 
     /// Applies the matrix without CORDIC, square roots, or normalization.
-    /// Preserves the length-at-most-one invariant of `UnitIntVector`.
+    /// Does not increase the input length; an approximate float input may
+    /// remain slightly longer than one.
     #[inline]
     pub fn apply(self, vector: UnitIntVector<I>) -> UnitIntVector<I> {
         let (sin, cos) = (self.sin.to_wide(), self.cos.to_wide());
         let (x, y) = (vector.x().to_wide(), vector.y().to_wide());
         let scale = FixedScale::<I>::DENOMINATOR;
-        // Each product is at most scale^2; even their sum fits I::Wide.
+        // Products and sums fit I::Wide for approximately unit inputs.
         UnitIntVector::from_components(
             I::from_wide((cos * x - sin * y) / scale),
             I::from_wide((sin * x + cos * y) / scale),

src/int/unit_vector.rs

@@ -9,16 +9,17 @@ use core::ops::Mul;
 /// An approximate unit direction stored as fixed-scale integer components.
 ///
 /// Obtain one with [`IntVector::fast_normalize`] or [`Self::normalize_with_float`].
-/// The represented components are
-/// `x() / DENOMINATOR` and `y() / DENOMINATOR`, each in `[-1, 1]`. The length is
-/// approximately one and never exceeds it.
+/// The represented components are `x() / DENOMINATOR` and `y() / DENOMINATOR`.
+/// Floating-point construction is approximate: rounding may make the length
+/// slightly greater than one. Integer normalization via `fast_normalize` and
+/// checked conversion via [`Self::try_from_float`] keep the length at most one.
 ///
 /// Integer normalization via `fast_normalize` favors speed over precision:
 /// it keeps about 6, 14, or 30 bits
 /// of direction precision for `i16`, `i32`, or `i64`, respectively.
 /// The storage scale does not imply that all stored bits are accurate.
-/// [`Rotation::apply`](crate::int::angle::Rotation::apply) preserves the upper
-/// length bound, but repeated rotations accumulate contraction and angular
+/// [`Rotation::apply`](crate::int::angle::Rotation::apply) does not increase
+/// length, but repeated rotations accumulate contraction and angular
 /// error; the normalization precision above is not a bound on that accumulation.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct UnitIntVector<T: IntNumber = i32> {
@@ -27,7 +28,7 @@ pub struct UnitIntVector<T: IntNumber = i32> {
 }
 
 impl<T: IntNumber> UnitIntVector<T> {
-    // Only for arithmetic that proves the resulting norm is at most one.
+    // The caller supplies an approximately unit or shorter nonzero vector.
     #[inline(always)]
     pub(crate) fn from_components(x: T, y: T) -> Self {
         Self { x, y }
@@ -47,23 +48,37 @@ impl<T: IntNumber> UnitIntVector<T> {
         if x.abs() > 1.0 || y.abs() > 1.0 {
             return None;
         }
-        let scale = Self::DENOMINATOR.to_f64();
-        let x = T::from_rounded_float(libm::trunc(x * scale));
-        let y = T::from_rounded_float(libm::trunc(y * scale));
-        let (wx, wy) = (x.to_wide(), y.to_wide());
+        let unit = Self::from_float_unchecked(x, y);
+        let (wx, wy) = (unit.x.to_wide(), unit.y.to_wide());
         let squared = wx * wx + wy * wy;
         if squared == T::Wide::ZERO || squared > Self::DENOMINATOR * Self::DENOMINATOR {
             return None;
         }
-        Some(Self { x, y })
+        Some(unit)
+    }
+
+    /// Converts already prepared floating-point components without validation
+    /// or normalization. Components are scaled and truncated toward zero.
+    ///
+    /// The caller supplies finite components of an approximately unit or shorter
+    /// vector that remains nonzero after quantization. Small floating-point
+    /// overshoots above unit length are accepted. Use [`Self::try_from_float`]
+    /// when the fixed-scale length must be checked against one.
+    #[inline]
+    pub fn from_float_unchecked<F: FloatNumber>(x: F, y: F) -> Self {
+        let scale = Self::DENOMINATOR.to_f64();
+        Self {
+            x: T::from_float(x.to_f64() * scale),
+            y: T::from_float(y.to_f64() * scale),
+        }
     }
 
     /// Normalizes an integer vector using f64 arithmetic, returning `None` only
     /// for the zero vector. Supports the full built-in wide component range,
     /// including i128::MIN; no integer products of the input are formed.
     ///
-    /// Axis directions are exact. Other directions are contracted slightly
-    /// before conversion so their fixed-scale length never exceeds one.
+    /// This is an approximate, unchecked normalization: rounding may make the
+    /// output length slightly greater than one, including for axis directions.
     /// Precision is limited by f64 arithmetic and the output component scale.
     /// When normalizing a point difference, subtract the integer points first
     /// to retain small differences between large coordinates.
@@ -74,16 +89,9 @@ impl<T: IntNumber> UnitIntVector<T> {
         }
         let x = vector.x.to_f64();
         let y = vector.y.to_f64();
-        if x == 0.0 {
-            return Self::try_from_float(0.0, y.signum());
-        }
-        if y == 0.0 {
-            return Self::try_from_float(x.signum(), 0.0);
-        }
         // Squaring and adding even two i128 components fits in f64.
-        let length = FloatNumber::sqrt(x * x + y * y);
-        let inward = 1.0 - 4.0 * f64::EPSILON;
-        Self::try_from_float(x / length * inward, y / length * inward)
+        let inv_length = 1.0 / FloatNumber::sqrt(x * x + y * y);
+        Some(Self::from_float_unchecked(x * inv_length, y * inv_length))
     }
 
     /// The stored integer value representing one: 2^14, 2^30, or 2^62.

tests/float_normalize_tests.rs

@@ -14,15 +14,11 @@ macro_rules! check_normalize {
                 }
                 let unit = result.expect("every nonzero wide vector can be normalized");
                 let (a, b) = (unit.x() as $wide, unit.y() as $wide);
-                assert!(a * a + b * b <= scale * scale);
                 assert!(a != 0 || b != 0);
-                if y == 0 {
-                    assert_eq!((a, b), (x.signum() * scale, 0));
-                } else if x == 0 {
-                    assert_eq!((a, b), (0, y.signum() * scale));
-                }
                 let length = (x as f64).hypot(y as f64);
                 let tolerance = 1.0 / scale as f64 + 8.0 * f64::EPSILON;
+                let norm = (a as f64 / scale as f64).hypot(b as f64 / scale as f64);
+                assert!((norm - 1.0).abs() <= 2.0 * tolerance);
                 assert!((a as f64 / scale as f64 - x as f64 / length).abs() <= tolerance);
                 assert!((b as f64 / scale as f64 - y as f64 / length).abs() <= tolerance);
                 if x != <$wide>::MIN && y != <$wide>::MIN {
@@ -63,3 +59,14 @@ macro_rules! check_normalize {
 check_normalize!(normalize_i16, i16, i32);
 check_normalize!(normalize_i32, i32, i64);
 check_normalize!(normalize_i64, i64, i128);
+
+#[test]
+fn near_axis_roundoff_does_not_reject_nonzero_vector() {
+    let unit = UnitIntVector::<i64>::normalize_with_float(IntVector::new(1 << 30, 1)).unwrap();
+    let scale = UnitIntVector::<i64>::DENOMINATOR;
+    let (x, y) = (unit.x() as i128, unit.y() as i128);
+    // f64 loses the small squared component. A slight overshoot is intentional.
+    assert!(x * x + y * y > scale * scale);
+    assert!((x as f64 / scale as f64 - 1.0).abs() <= f64::EPSILON);
+    assert!(y > 0);
+}

tests/float_unit_vector_tests.rs

@@ -14,6 +14,7 @@ macro_rules! float_conversion {
                 (0.5, 0.5),
             ] {
                 let unit = UnitIntVector::<$int>::try_from_float(x, y).unwrap();
+                assert_eq!(unit, UnitIntVector::<$int>::from_float_unchecked(x, y));
                 let (a, b) = (unit.x() as $wide, unit.y() as $wide);
                 assert!(a * a + b * b <= s * s);
                 assert!((a as f64 / s as f64 - x).abs() <= 1.0 / s as f64);
@@ -26,6 +27,10 @@ macro_rules! float_conversion {
                 let (sin, cos) = libm::sincos(angle);
                 let inward = 1.0 - 8.0 * f64::EPSILON;
                 let unit = UnitIntVector::<$int>::try_from_float(cos * inward, sin * inward).unwrap();
+                assert_eq!(
+                    unit,
+                    UnitIntVector::<$int>::from_float_unchecked(cos * inward, sin * inward)
+                );
                 let (a, b) = (unit.x() as $wide, unit.y() as $wide);
                 assert!(a * a + b * b <= s * s);
             }