Merge branch 'quaternions' into quaternion/elfns

Author: markuswntr

Sources/QuaternionModule/Norms.swift

@@ -77,8 +77,19 @@ extension Quaternion {
   /// - `.lengthSquared`
   @_transparent
   public var length: RealType {
+    let naive = lengthSquared
+    guard naive.isNormal else { return carefulLength }
+    return .sqrt(naive)
+  }
+
+  //  Internal implementation detail of `length`, moving slow path off
+  //  of the inline function.
+  @usableFromInline
+  internal var carefulLength: RealType {
     guard isFinite else { return .infinity }
-    return .sqrt(lengthSquared)
+    guard !magnitude.isZero else { return .zero }
+    // Unscale the quaternion, calculate its length and rescale the result
+    return divided(by: magnitude).length * magnitude
   }
 
   /// The squared length `(r*r + x*x + y*y + z*z)`.

Sources/QuaternionModule/Quaternion.swift

@@ -186,6 +186,7 @@ extension Quaternion {
   /// - `.isNormal`
   /// - `.isSubnormal`
   /// - `.isZero`
+  /// - `.isReal`
   /// - `.isPure`
   @_transparent
   public var isFinite: Bool {
@@ -206,6 +207,7 @@ extension Quaternion {
   /// - `.isFinite`
   /// - `.isSubnormal`
   /// - `.isZero`
+  /// - `.isReal`
   /// - `.isPure`
   @_transparent
   public var isNormal: Bool {
@@ -228,6 +230,7 @@ extension Quaternion {
   /// - `.isFinite`
   /// - `.isNormal`
   /// - `.isZero`
+  /// - `.isReal`
   /// - `.isPure`
   @_transparent
   public var isSubnormal: Bool {
@@ -243,13 +246,40 @@ extension Quaternion {
   /// - `.isFinite`
   /// - `.isNormal`
   /// - `.isSubnormal`
+  /// - `.isReal`
   /// - `.isPure`
   @_transparent
   public var isZero: Bool {
     components == .zero
   }
 
-  /// True if this value is only defined by the imaginary part (`real == .zero`)
+  /// True if this quaternion is real.
+  ///
+  /// A quaternion is real if *all* imaginary components are zero.
+  ///
+  /// See also:
+  /// -
+  /// - `.isFinite`
+  /// - `.isNormal`
+  /// - `.isSubnormal`
+  /// - `.isZero`
+  /// - `.isPure`
+  @_transparent
+  public var isReal: Bool {
+    imaginary == .zero
+  }
+
+  /// True if this quaternion is pure.
+  ///
+  /// A quaternion is pure if the real component is zero.
+  ///
+  /// See also:
+  /// -
+  /// - `.isFinite`
+  /// - `.isNormal`
+  /// - `.isSubnormal`
+  /// - `.isZero`
+  /// - `.isReal`
   @_transparent
   public var isPure: Bool {
     real.isZero

Tests/QuaternionTests/PropertyTests.swift

@@ -34,6 +34,20 @@ final class PropertyTests: XCTestCase {
     XCTAssertEqual(Quaternion<T>.zero.length, .zero)
     XCTAssertEqual(Quaternion<T>(real: .zero, imaginary: -.zero).length, .zero)
     XCTAssertEqual(Quaternion<T>(real: -.zero, imaginary: -.zero).length, .zero)
+    // Check for overflow and underflow when calculating the length
+    XCTAssertEqual(Quaternion<T>(real: .greatestFiniteMagnitude, imaginary: 0, 0, 0).length, .greatestFiniteMagnitude)
+    XCTAssertEqual(Quaternion<T>(real: 0, imaginary: -.greatestFiniteMagnitude, 0, 0).length, .greatestFiniteMagnitude)
+    XCTAssertEqual(Quaternion<T>(real: 0, imaginary: 0, .leastNormalMagnitude, 0).length, .leastNormalMagnitude)
+    XCTAssertEqual(Quaternion<T>(real: 0, imaginary: 0, 0, -.leastNormalMagnitude).length, .leastNormalMagnitude)
+    // The properties of pure and real
+    XCTAssertTrue(Quaternion<T>.zero.isPure) // zero quaternion is both, pure...
+    XCTAssertTrue(Quaternion<T>.zero.isReal) // and real
+    XCTAssertFalse(Quaternion<T>(1).isPure)
+    XCTAssertTrue(Quaternion<T>(1).isReal)
+    XCTAssertTrue(Quaternion<T>(real: .zero, imaginary: 1, 0, 0).isPure)
+    XCTAssertFalse(Quaternion<T>(real: .zero, imaginary: 1, 0, 0).isReal)
+    XCTAssertFalse(Quaternion<T>(from: SIMD4(repeating: 1)).isPure)
+    XCTAssertFalse(Quaternion<T>(from: SIMD4(repeating: 1)).isReal)
   }
 
   func testProperties() {