Make Quantity extensible via RawRepresentable struct

Replaces the closed `Quantity` enum with a `RawRepresentable` struct that
exposes the same built-in dimensions as static constants, resolving the
long-standing TODO about extensibility.

Callers can now define their own dimensions (e.g. a `Money` dimension for
cost calculations) with a static extension, without forking the package or
repurposing an unrelated base quantity like `Amount`:

    extension Quantity { static let money = Quantity(rawValue: "Money") }

All existing call sites are source-compatible: `.Length`-style literals,
`[Quantity: Int]` dictionary keys, and the `\\Quantity.rawValue` keypath all
continue to work. The one behavioral change is that the synthesized failable
`init?(rawValue:)` becomes a non-failable `init(rawValue:)`, since any string
is now a valid dimension.

Adds QuantityTests covering custom-dimension identity, arithmetic
cancellation, and dimension description. Documents the feature under a new
'Custom Dimensions' README section.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: rstacpoole

README.md

@@ -194,6 +194,38 @@ let weeklyCartons = try (workforce * personPickRate).convert(to: carton / .week)
 print(weeklyCartons)  // Prints '350.0 carton/week'
 ```
 
+### Custom Dimensions
+
+The built-in `Quantity` dimensions (`Length`, `Mass`, `Time`, etc.) cover the ISQ base
+quantities, but you can define your own dimension when none of them fit — for example, a
+`Money` dimension for cost calculations. Because `Quantity` is `RawRepresentable`, you can
+add one with a static extension:
+
+```swift
+extension Quantity {
+    static let money = Quantity(rawValue: "Money")
+}
+```
+
+Your dimension then behaves like any built-in one. Here a concrete rate of `$/m^3` is
+multiplied by a volume in `m^3`, and the volume cancels to leave a pure cost:
+
+```swift
+let registry = try RegistryBuilder().addUnit(
+    name: "dollar",
+    symbol: "$",
+    dimension: [.money: 1]
+).registry()
+let dollar = try Unit(fromSymbol: "$", registry: registry)
+
+let rate = Measurement(value: 180, unit: dollar / .meter.pow(3)) // $180 per m^3
+let volume = Measurement(value: 24, unit: .meter.pow(3))         // 24 m^3
+print(rate * volume) // Prints '4320.0 $'
+```
+
+Unlike repurposing an unrelated base quantity such as `Amount`, a dedicated dimension can't
+silently cancel against unrelated units. Use a unique `rawValue` for each distinct dimension.
+
 ## CLI
 
 The easiest way to install the CLI is with brew:

Sources/Units/Quantity.swift

@@ -1,17 +1,32 @@
-/// A dimension of measurement. These may be combined to form composite dimensions and measurements
-public enum Quantity: String, Sendable {
-    // TODO: Consider changing away from enum for extensibility
+/// A dimension of measurement. These may be combined to form composite dimensions and measurements.
+///
+/// `Quantity` is `RawRepresentable` rather than an enum so that callers can define their own
+/// dimensions without modifying this package. Add one with a static extension:
+///
+/// ```swift
+/// extension Quantity {
+///     static let money = Quantity(rawValue: "Money")
+/// }
+/// ```
+///
+/// Use a unique `rawValue` for each distinct dimension — equality and hashing are based on it.
+public struct Quantity: RawRepresentable, Hashable, Sendable {
+    public let rawValue: String
+
+    public init(rawValue: String) {
+        self.rawValue = rawValue
+    }
 
     // Base ISQ quantities: https://en.wikipedia.org/wiki/International_System_of_Quantities#Base_quantities
-    case Amount
-    case Current
-    case Length
-    case Mass
-    case Temperature
-    case Time
-    case LuminousIntensity
+    public static let Amount = Quantity(rawValue: "Amount")
+    public static let Current = Quantity(rawValue: "Current")
+    public static let Length = Quantity(rawValue: "Length")
+    public static let Mass = Quantity(rawValue: "Mass")
+    public static let Temperature = Quantity(rawValue: "Temperature")
+    public static let Time = Quantity(rawValue: "Time")
+    public static let LuminousIntensity = Quantity(rawValue: "LuminousIntensity")
 
     // Extended SI Units: https://en.wikipedia.org/wiki/Non-SI_units_mentioned_in_the_SI
-    case Angle
-    case Data
+    public static let Angle = Quantity(rawValue: "Angle")
+    public static let Data = Quantity(rawValue: "Data")
 }

Tests/UnitsTests/QuantityTests.swift

@@ -0,0 +1,63 @@
+import Units
+import XCTest
+
+/// A user-defined dimension, declared outside the package. This is the capability
+/// that `Quantity` being `RawRepresentable` (rather than a closed enum) enables.
+private extension Quantity {
+    static let money = Quantity(rawValue: "Money")
+}
+
+class QuantityTests: XCTestCase {
+    /// Built-in quantities keep their stable string raw values.
+    func testBuiltInRawValues() {
+        XCTAssertEqual(Quantity.Length.rawValue, "Length")
+        XCTAssertEqual(Quantity.Time.rawValue, "Time")
+        XCTAssertEqual(Quantity(rawValue: "Mass"), .Mass)
+    }
+
+    /// A custom dimension is distinct from every built-in one and equal to itself.
+    func testCustomQuantityIdentity() {
+        XCTAssertEqual(Quantity.money, Quantity(rawValue: "Money"))
+        XCTAssertNotEqual(Quantity.money, .Length)
+        XCTAssertNotEqual(Quantity.money, .Amount)
+
+        // Usable as a dictionary key alongside built-ins.
+        let dimension: [Quantity: Int] = [.money: 1, .Length: -3]
+        XCTAssertEqual(dimension[.money], 1)
+        XCTAssertEqual(dimension[.Length], -3)
+    }
+
+    /// A unit on a custom dimension participates in dimensional arithmetic:
+    /// a rate of `$/m^3` multiplied by a volume in `m^3` cancels to pure `$`.
+    func testCustomDimensionCancelsInArithmetic() throws {
+        let registry = try RegistryBuilder().addUnit(
+            name: "dollar",
+            symbol: "$",
+            dimension: [.money: 1]
+        ).registry()
+
+        let dollar = try Unit(fromSymbol: "$", registry: registry)
+        let cubicMeter = Unit.meter.pow(3)
+
+        let rate = Measurement(value: 180, unit: dollar / cubicMeter) // $180 per m^3
+        let volume = Measurement(value: 24, unit: cubicMeter) // 24 m^3
+        let cost = rate * volume
+
+        XCTAssertEqual(cost.value, 4320, accuracy: 1e-9)
+        // The volume cancels, leaving a pure money dimension.
+        XCTAssertEqual(cost.unit.dimension, [.money: 1])
+        XCTAssertTrue(cost.isDimensionallyEquivalent(to: Measurement(value: 1, unit: dollar)))
+    }
+
+    /// A custom dimension surfaces in the human-readable dimension description.
+    func testCustomDimensionDescription() throws {
+        let registry = try RegistryBuilder().addUnit(
+            name: "dollar",
+            symbol: "$",
+            dimension: [.money: 1]
+        ).registry()
+
+        let dollar = try Unit(fromSymbol: "$", registry: registry)
+        XCTAssertEqual(dollar.dimensionDescription(), "Money")
+    }
+}