feat: Add/Subtract support dimensionally equivalent units

More specifically, addition and subtraction no longer require that units match exactly. Instead, the units must only be dimensionally equivalent, and the left-hand unit is preserved as the unit of the output measurement.

Author: NeedleInAJayStack

README.md

@@ -23,7 +23,7 @@ This package has no other dependencies.
 
 ## Usage
 
-Users should interact primarily with the `Measurement` struct. Here are a few usage examples:
+Users should interact primarily with the `Measurement` struct. Here are a examples of arithmetic:
 
 ```swift
 let drivingSpeed = 60.measured(in: .mile / .hour)
@@ -34,6 +34,8 @@ let drivingDistance = drivingSpeed * drivingTime
 print(drivingDistance.convert(to: .mile)) // Prints 30 mi
 ```
 
+Note that a measurement may be multiplied or divided by another measurement with any unit, resulting in a measurement that has a new-dimensioned unit (5 meters / 10 seconds ✅). However, addition and subtraction requires that both measurements have the same dimensionality (5 meters - 10 seconds ❌), otherwise a runtime error is thrown. If adding or subtracting two measurements with different units but the same dimensionality, the result retains the first measurement's unit (5 meters - 5 millimeters = 4.995 meters).
+
 The type names in this package align closely with the unit system provided by `Foundation`. This was intentional to provide a
 familiar nomenclature for Swift developers. The APIs have been designed to avoid namespace ambiguity in files where both `Units`
 and `Foundation` are imported as much as possible. However, if an issue arises, just qualify the desired package like so:

Sources/Units/Measurement/Measurement.swift

@@ -38,6 +38,10 @@ public struct Measurement: Equatable, Codable {
     /// - Parameter newUnit: The unit to convert this measurement to
     /// - Returns: A new measurement with the converted scalar value and provided unit of measure
     public func convert(to newUnit: Unit) throws -> Measurement {
+        if unit == newUnit {
+            // No conversion needed
+            return self
+        }
         guard unit.isDimensionallyEquivalent(to: newUnit) else {
             throw UnitError.incompatibleUnits(message: "Cannot convert \(unit) to \(newUnit)")
         }
@@ -52,9 +56,9 @@ public struct Measurement: Equatable, Codable {
     ///   - rhs: The right-hand-side measurement
     /// - Returns: A new measurement with the summed scalar values and the same unit of measure
     public static func + (lhs: Measurement, rhs: Measurement) throws -> Measurement {
-        try checkSameUnit(lhs, rhs)
+        let rhsValue = try rhs.convert(to: lhs.unit).value
         return Measurement(
-            value: lhs.value + rhs.value,
+            value: lhs.value + rhsValue,
             unit: lhs.unit
         )
     }
@@ -64,8 +68,8 @@ public struct Measurement: Equatable, Codable {
     ///   - lhs: The left-hand-side measurement
     ///   - rhs: The right-hand-side measurement
     public static func += (lhs: inout Measurement, rhs: Measurement) throws {
-        try checkSameUnit(lhs, rhs)
-        lhs.value = lhs.value + rhs.value
+        let rhsValue = try rhs.convert(to: lhs.unit).value
+        lhs.value = lhs.value + rhsValue
     }
 
     /// Subtract one measurement from another. The measurements must have the same unit.
@@ -75,9 +79,9 @@ public struct Measurement: Equatable, Codable {
     /// - Returns: A new measurement with the subtracted scalar values and the same unit of measure
     /// and the same unit of measure
     public static func - (lhs: Measurement, rhs: Measurement) throws -> Measurement {
-        try checkSameUnit(lhs, rhs)
+        let rhsValue = try rhs.convert(to: lhs.unit).value
         return Measurement(
-            value: lhs.value - rhs.value,
+            value: lhs.value - rhsValue,
             unit: lhs.unit
         )
     }
@@ -87,8 +91,8 @@ public struct Measurement: Equatable, Codable {
     ///   - lhs: The left-hand-side measurement
     ///   - rhs: The right-hand-side measurement
     public static func -= (lhs: inout Measurement, rhs: Measurement) throws {
-        try checkSameUnit(lhs, rhs)
-        lhs.value = lhs.value - rhs.value
+        let rhsValue = try rhs.convert(to: lhs.unit).value
+        lhs.value = lhs.value - rhsValue
     }
 
     /// Multiply the measurements. The measurements may have different units.

Tests/UnitsTests/MeasurementTests.swift

@@ -36,6 +36,13 @@ final class MeasurementTests: XCTestCase {
             accuracy: accuracy
         )
 
+        // Test that adding different units of the same dimension works
+        XCTAssertEqual(
+            try 5.measured(in: .meter) + 5.measured(in: .millimeter),
+            5.005.measured(in: .meter),
+        )
+
+        // Test that adding different dimensions throws an error
         XCTAssertThrowsError(
             try 5.measured(in: .meter) + 5.measured(in: .second)
         )
@@ -62,6 +69,13 @@ final class MeasurementTests: XCTestCase {
             accuracy: accuracy
         )
 
+        // Test that subtracting different units of the same dimension works
+        XCTAssertEqual(
+            try 5.measured(in: .meter) - 5.measured(in: .millimeter),
+            4.995.measured(in: .meter),
+        )
+
+        // Test that subtracting different dimensions throws an error
         XCTAssertThrowsError(
             try 5.measured(in: .meter) - 5.measured(in: .second)
         )