added Percent (not as Measurement)

Author: wildthink-pub

Justfile

@@ -0,0 +1,38 @@
+# Units Justfile
+# Command line support
+
+
+# About Units Commands
+_default:
+    @echo '{{ style("warning") }}Units Script Commands{{ NORMAL }}'
+    @echo @{{source_file()}}
+    @echo ""
+    @just -f {{source_file()}} --list
+
+# Install 'units' in /usr/local/bin
+install:
+    swift build -c release
+    cp .build/release/unit /usr/local/bin/
+
+# rm 'units' from /usr/local/bin
+uninstall:
+    rm /usr/local/bin/unit
+
+# Add swiftformat to git/pre-commit
+dev_setup:
+    echo "./Scripts/git_commit_hook.sh" > .git/hooks/pre-commit
+
+# Open Documentation
+docs:
+    open https://swiftpackageindex.com/NeedleInAJayStack/Units/v1.0.0/documentation/units
+
+git_origin := `git remote get-url origin`
+
+# repo/origin
+repo:
+    @echo {{git_origin}}
+
+# open repo/origin
+open-repo:
+    open {{git_origin}}
+

Sources/CLI/Convert.swift

@@ -31,6 +31,7 @@ struct Convert: ParsableCommand {
     @Argument(help: """
     The unit to convert to. This can either be a unit name, a unit symbol, or an equation of \
     unit symbols.
+    Example: unit convert 1_ft meter -> 0.3048 m
     """)
     var to: Units.Unit
 

Sources/CLI/List.swift

@@ -6,6 +6,10 @@ struct List: ParsableCommand {
         abstract: "Print a table of the available units, their symbols, and their dimensionality."
     )
 
+    @Option(name: .shortAndLong,
+        help: "Substring to filter on dimensions and symbols")
+    var filter: String? = nil
+    
     func run() throws {
         let units = registry.allUnits().sorted { u1, u2 in
             u1.name <= u2.name
@@ -17,7 +21,9 @@ struct List: ParsableCommand {
             "dimension",
         ]
 
-        let rows = units.map { unit in
+        let rows = units
+            .filter({ $0.contains(filter)})
+            .map { unit in
             [
                 unit.name,
                 unit.symbol,
@@ -59,3 +65,11 @@ struct List: ParsableCommand {
         }
     }
 }
+
+extension Units.Unit {
+    func contains(_ substring: String?) -> Bool {
+        guard let substring else { return true }
+        return self.symbol.contains(substring)
+        || self.dimensionDescription().contains(substring)
+    }
+}

Sources/Units/Measurement/Percent+Measurement.swift

@@ -0,0 +1,184 @@
+//
+//  Percent.swift
+//  Units
+//
+//  Created by Jason Jobe on 9/5/25.
+//
+
+import Foundation
+/*
+ NOTE: Should consider introducing `protocol Scalar`
+ based on `VectorArithmetic`
+ */
+
+/**
+ 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.
+ 
+ Here’s how math operators work with percentages in typical calculations:
+ 
+ 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.
+ 
+ Example Table
+ ===========
+ Expression    Decimal Form           Result
+ ------------------------------
+ 100 * 25%     100 * 0.25                25
+ 100 / 30%      100 / 0.3                   333.33
+ 100 + 10%     100 + (100*0.10)     110
+ 
+ 
+ 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 private(set) var magnitude: Double
+    
+    /// Create a new Percent
+    /// - Parameters:
+    ///   - value: The magnitude of the percent
+    public init(
+        magnitude: Double
+    ) {
+        self.magnitude = magnitude
+    }
+    
+    func percent(of measure: Measurement) -> Measurement {
+        .init(value: magnitude * measure.value, unit: measure.unit)
+    }
+    
+    func percent(of other: Double) -> Double {
+        magnitude * other
+    }
+}
+
+// MARK: Percent as Unit
+extension Percent {
+    public var unit: Unit { Self.unit }
+    
+    public static let unit = Unit(
+        definedBy: try! DefinedUnit(
+        name: "percent",
+        symbol: "%",
+        dimension: [:],
+        coefficient: 0.01
+    ))
+}
+
+// MARK: Numeric Conformance
+public extension Percent {
+    init(integerLiteral value: Double) {
+        magnitude = value
+    }
+    
+    static func *= (lhs: inout Percent, rhs: Percent) {
+        lhs.magnitude *= rhs.magnitude
+    }
+    
+    static func - (lhs: Percent, rhs: Percent) -> Percent {
+        Percent(magnitude: lhs.magnitude - rhs.magnitude)
+    }
+    
+    init?<T>(exactly source: T) where T : BinaryInteger {
+        magnitude = Double(source)
+    }
+    
+    static func * (lhs: Percent, rhs: Percent) -> Percent {
+        Percent(magnitude: lhs.magnitude * rhs.magnitude)
+    }
+    
+    static func + (lhs: Percent, rhs: Percent) -> Percent {
+        Percent(magnitude: lhs.magnitude + rhs.magnitude)
+    }
+}
+
+postfix operator %
+
+extension BinaryInteger {
+    public static postfix func % (value: Self) -> Percent {
+        Percent(magnitude: Double(value)/100)
+    }
+}
+
+extension BinaryFloatingPoint {
+    public static postfix func % (value: Self) -> Percent {
+        Percent(magnitude: Double(value)/100)
+    }
+}
+
+// AdditiveArithmetic operations `*` and `/`
+
+public extension Measurement {
+    /// Calculate the percentage of the Measurement
+    /// - Parameters:
+    ///   - lhs: The left-hand-side measurement
+    ///   - rhs: The right-hand-side measurement
+    /// - Returns: A new measurement with the summed scalar values and the same unit of measure
+    @_disfavoredOverload
+    static func + (lhs: Measurement, rhs: Percent) -> Measurement {
+        return Measurement(
+            value: lhs.value + rhs.percent(of: lhs.value),
+            unit: lhs.unit
+        )
+    }
+    
+    @_disfavoredOverload
+    static func - (lhs: Measurement, rhs: Percent) -> Measurement {
+        return Measurement(
+            value: lhs.value - rhs.percent(of: lhs.value),
+            unit: lhs.unit
+        )
+    }
+    
+    @_disfavoredOverload
+    static func += (lhs: inout Measurement, rhs: Percent) {
+        lhs = lhs + rhs
+    }
+
+    @_disfavoredOverload
+    static func -= (lhs: inout Measurement, rhs: Percent) {
+        lhs = lhs - rhs
+    }
+
+}
+
+// Scalar operations `*` and `/`
+public extension Measurement {
+    
+    @_disfavoredOverload
+    static func * (lhs: Measurement, rhs: Percent) -> Measurement {
+        return Measurement(
+            value: lhs.value * rhs.magnitude,
+            unit: lhs.unit
+        )
+    }
+
+    @_disfavoredOverload
+    static func / (lhs: Measurement, rhs: Percent) -> Measurement {
+        return Measurement(
+            value: lhs.value / rhs.magnitude,
+            unit: lhs.unit
+        )
+    }
+
+}

Tests/UnitsTests/UnitTests.swift

@@ -80,6 +80,20 @@ final class UnitTests: XCTestCase {
         )
     }
 
+    func testPercent() throws {
+        let value1 = 100.measured(in: .none)
+        
+        XCTAssertEqual(Percent.unit.symbol, "%")
+
+        XCTAssertEqual(1%, 1%)
+    
+        XCTAssertEqual(110.measured(in: .none), value1 + 10%)
+        XCTAssertEqual(90.measured(in: .none), value1 - 10%)
+
+        XCTAssertEqual(10.measured(in: .none), value1 * 10%)
+        XCTAssertEqual(1_000.measured(in: .none), value1 / 10%)
+    }
+
     func testSymbol() throws {
         XCTAssertEqual(
             Unit.meter.symbol,