Measurement FormatStyle (#1)

* FormatStyle WIP

* added FormatStyle tests

* updated README and @available

---------

Co-authored-by: Jason Jobe <box2019@jasonjobe.com>

Author: wildthink

README.md

@@ -194,6 +194,56 @@ let weeklyCartons = try (workforce * personPickRate).convert(to: carton / .week)
 print(weeklyCartons)  // Prints '350.0 carton/week'
 ```
 
+### Percent
+
+While technically not a `Measurement`, the use of the percent symbol ('%') is still useful
+in conveying the "semanantics" of a scaler value so we include it in this package.
+
+Here’s how math operators work with percentages in typical calculations:
+
+Math operators with percentages treat the percent as its decimal equivalent 
+(e.g., 25% = 0.25) but in the case of `+` and `-` the calculation is less direct.
+ 
+#### Multiplication (100 * 25%)
+ 
+ When you multiply a number by a percentage, you’re finding that percent of the number.
+ • 25% is the same as 0.25.
+ • So, 100 * 25% = 100 * 0.25 = 25.
+ 
+#### Division (100 / 30%)
+ 
+ Dividing by a percentage means dividing by its decimal form.
+ • 30% is 0.3.
+ • So, 100 / 30% = 100 / 0.3 ≈ 333.33.
+ 
+#### Addition (100 + 10%)
+ 
+ Adding a percentage to a number is less direct, but usually means increasing the number by that percent.
+ • 10% of 100 is 10.
+ • So, 100 + 10% = 100 + (100 * 0.10) = 110.
+ 
+#### General Rule
+ • Percent means “per hundred,” so 25% = 25/100 = 0.25.
+ • Replace the percent with its decimal equivalent before performing the operation.
+ 
+
+### FormatStyle
+
+The `Measurement.Formatter` provides the `formatted` method to enable the
+setting of the `NumberFormatStyleConfiguration.Precision` for String output.
+
+Example Use:
+
+```
+    let measure = 28.123.measured(in: .meter)
+
+    measure.formatted() // -> "28.123 m"
+    measure.formatted(precision: .significantDigits(1) // ->  "30 m"
+    measure.formatted(precision: .significantDigits(3)) // -> "28.1 m"
+    measure.formatted(precision: 
+        .integerAndFractionLength(integer: 2, fraction: 0)) // ->  "28 m"
+```
+
 ## CLI
 
 The easiest way to install the CLI is with brew:

Sources/Units/Measurement/Measurement.swift

@@ -194,3 +194,58 @@ extension Measurement: ExpressibleByFloatLiteral {
 }
 
 extension Measurement: Sendable {}
+
+// MARK: FormatStyle
+@available(macOS 12.0, iOS 15.0, *)
+public extension Measurement {
+    
+    func formatted<Style: FormatStyle>(
+        _ style: Style
+    ) -> Style.FormatOutput where Style.FormatInput == Self {
+        style.format(self)
+    }
+}
+
+@available(macOS 12.0, iOS 15.0, *)
+public extension Measurement {
+    typealias Precision = NumberFormatStyleConfiguration.Precision
+
+    struct Formatter<Output> {
+        let format: (Measurement) -> Output
+    }
+    
+    func formatted<Output>(_ formatter: Formatter<Output>) -> Output {
+        formatter.format(self)
+    }
+    
+    func formatted(_ formatter: Formatter<String> = .measurement()) -> String {
+        formatter.format(self)
+    }
+    
+    @_disfavoredOverload
+    func formatted(precision: Precision? = nil) -> String {
+        formatted(.measurement(precision: precision))
+    }
+}
+
+@available(macOS 12.0, iOS 15.0, *)
+extension Measurement.Formatter where Output == String {
+    public typealias Precision = NumberFormatStyleConfiguration.Precision
+    
+    public static func measurement(precision: Precision? = nil) -> Self {
+        .init { value in
+            switch (value.unit, precision) {
+                case (.none, .none):
+                    "\(value.value.formatted(.number))"
+                case (.none, .some(let p)):
+                    "\(value.value.formatted(.number.precision(p)))"
+                case (let u, .none):
+                    "\(value.value.formatted(.number)) \(u)"
+                    
+                case (let u, .some(let p)):
+                    "\(value.value.formatted(.number.precision(p))) \(u)"
+            }
+        }
+    }
+}
+

Sources/Units/Measurement/Percent+Measurement.swift

@@ -43,7 +43,7 @@ import Foundation
 
  If you see a percent sign in a calculation, just convert it to a decimal and proceed as usual. If you want to know how subtraction works with percentages, or how to handle more complex expressions, let me know!
  */
-public struct Percent: Numeric, Equatable, Codable {
+public struct Percent: Numeric, Codable, Sendable {
 
     public private(set) var magnitude: Double
 
@@ -65,6 +65,14 @@ public struct Percent: Numeric, Equatable, Codable {
     }
 }
 
+extension Percent: Equatable {
+    /// Implemented as "nearly" equal
+    public static func ==(lhs: Percent, rhs: Percent) -> Bool {
+        lhs.magnitude >= rhs.magnitude.nextDown
+        && lhs.magnitude <= lhs.magnitude.nextUp
+    }
+}
+
 extension Measurement {
     public var isPercent: Bool {
         self.unit == Percent.unit
@@ -201,3 +209,72 @@ public extension Measurement {
         )
     }
 }
+
+extension Percent: Comparable {
+    public static func < (lhs: Self, rhs: Self) -> Bool {
+        lhs.magnitude < rhs.magnitude
+    }
+}
+
+extension Percent {
+    /**
+     Returns a random value within the given range.
+     
+     ```
+     Percent.random(in: 10%...20%)
+     // 10%, 11%, 12%, 19.98%, etc.
+     ```
+     */
+    public static func random(in range: ClosedRange<Self>) -> Self {
+        self.init(magnitude: .random(in: range.lowerBound.magnitude...range.upperBound.magnitude))
+    }
+}
+
+// MARK: FormatStyle
+@available(macOS 12.0, iOS 15.0, *)
+public extension Percent {
+    
+    func formatted<Style: FormatStyle>(
+        _ style: Style
+    ) -> Style.FormatOutput where Style.FormatInput == Self {
+        style.format(self)
+    }
+}
+
+public extension Percent {
+    struct Formatter<Output> {
+        let format: (Percent) -> Output
+    }
+    
+    func formatted<Output>(_ formatter: Formatter<Output>) -> Output {
+        formatter.format(self)
+    }
+}
+
+@available(macOS 12.0, iOS 15.0, *)
+public extension Percent {
+    func formatted(_ formatter: Formatter<String> = .percent) -> String {
+        formatter.format(self)
+    }
+    
+    func formatted(fractionDigits: Int) -> String {
+        Formatter(fractionDigits: fractionDigits).format(self)
+    }
+}
+
+@available(macOS 12.0, iOS 15.0, *)
+public extension Percent.Formatter where Output == String {
+    
+    init (fractionDigits: Int) {
+        self.init { value in
+            value.magnitude
+                .formatted(.percent.precision(.fractionLength(fractionDigits)))
+        }
+    }
+    
+    static var percent: Self {
+        .init { value in
+            return value.magnitude.formatted(.percent)
+        }
+    }
+}

Tests/UnitsTests/MeasurementTests.swift

@@ -600,4 +600,12 @@ final class MeasurementTests: XCTestCase {
             accuracy: accuracy
         )
     }
+    
+    func testFormatStyle() {
+        let measure = 28.123.measured(in: .meter)
+        XCTAssertEqual(measure.formatted(), "28.123 m")
+        XCTAssertEqual(measure.formatted(precision: .significantDigits(1)), "30 m")
+        XCTAssertEqual(measure.formatted(precision: .significantDigits(3)), "28.1 m")
+        XCTAssertEqual(measure.formatted(precision: .integerAndFractionLength(integer: 2, fraction: 0)), "28 m")
+    }
 }

Tests/UnitsTests/PercentTests.swift

@@ -9,6 +9,7 @@
 import XCTest
 
 final class PercentTests: XCTestCase {
+    
     func testParse() throws {
         XCTAssertEqual(
             try Expression("10m + 25%"),
@@ -38,7 +39,20 @@ final class PercentTests: XCTestCase {
             try Expression("10m / 25%").solve(),
             40.measured(in: .meter)
         )
-
+    }
+    
+    func testPercentCalculation() {
+        XCTAssertEqual(50% * 50%, 25%)
+        XCTAssertEqual(50% + 5.8%, 55.8%)
+        XCTAssertEqual(50% - 50%, 0%)
+        XCTAssertEqual(50% - 5.8%, 44.2%)
+    }
+    
+    func testPercentFormat() {
+        XCTAssertEqual(30%.formatted(), "30%")
+        XCTAssertEqual(28.5%.formatted(), "28.5%")
+        XCTAssertEqual(28.33%.formatted(), "28.33%")
+        XCTAssertEqual(28.33%.formatted(fractionDigits: 1), "28.3%")
+        XCTAssertEqual(28.33%.formatted(fractionDigits: 0), "28%")
     }
 }
-