feat!: Removes reliance on registry singleton

This does so by introducing a RegistryBuilder that custom units must be attached to, and is used for all Unit lookups. This was (rightfully) required by Swift 6 memory safety, since the existing implementation had issues with shared mutable state. I attempted to minimize breaking changes, but some were required.

Author: NeedleInAJayStack

README.md

@@ -121,40 +121,57 @@ For a list of the default units and their conversion factors, see the [`DefaultU
 
 ## Custom Units
 
-To extend this package, users can define their own custom units using `Unit.define`:
+The unit system is backed by a `Registry` that maps unit symbols to their metadata. To add new units, use `RegistryBuilder`, and pass it to any operation that converts from a `String` to a `Unit`:
 
 ```swift
-let centifoot = try Unit.define(
+let registryBuilder = RegistryBuilder()
+registryBuilder.addUnit(
     name: "centifoot",
     symbol: "cft",
     dimension: [.Length: 1],
     coefficient: 0.003048 // This is the conversion to meters
 )
+let registry = registryBuilder.registry()
+let centifoot = try Unit(fromSymbol: "cft", registry: registry)
 
 let measurement = Measurement(value: 5, unit: centifoot)
 print(5.measured(in: .foot).convert(to: centifoot))
 ```
 
 This returns a Unit object that can be used in arithmetic, conversions, and serialization.
 
+### Encoding and Decoding
+
+When using custom units, you must provide the custom registry to the encoder or decoder using `userInfo`:
+
+```swift
+let decoder = JSONDecoder()
+decoder.userInfo[Unit.registryUserInfoKey] = registry  // Required to recognize custom units.
+try decoder.decode(Unit.self, from: #""cft/s""#.data(using: .utf8))
+```
+
 ### Non-scientific Units
 
 For "non-scientific" units, it is typically appropriate to use the `Amount` quantity. Through this approach, you can easily build up an impromptu conversion system on the fly. For example:
 
 ```swift
-let apple = try Unit.define(
+let registryBuilder = RegistryBuilder()
+try registryBuilder.addUnit(
     name: "apple",
     symbol: "apple",
     dimension: [.Amount: 1],
     coefficient: 1
 )
-
-let carton = try Unit.define(
+try registryBuilder.addUnit(
     name: "carton",
     symbol: "carton",
     dimension: [.Amount: 1],
     coefficient: 48
 )
+let registry = registryBuilder.registry()
+
+let apple = try Unit(fromSymbol: "apple", registry: registry)
+let carton = try Unit(fromSymbol: "carton", registry: registry)
 
 let harvest = 288.measured(in: apple)
 print(harvest.convert(to: carton)) // Prints '6.0 carton'
@@ -163,48 +180,20 @@ print(harvest.convert(to: carton)) // Prints '6.0 carton'
 We can extend this example to determine how many cartons a group of people can pick in a week:
 
 ```swift
-let person = try Unit.define(
+try registryBuilder.addUnit(
     name: "person",
     symbol: "person",
     dimension: [.Amount: 1],
     coefficient: 1
 )
+let person = try Unit(fromSymbol: "person", registry: registryBuilder.registry())
 
 let personPickRate = 600.measured(in: apple / .day / person)
 let workforce = 4.measured(in: person)
 let weeklyCartons = try (workforce * personPickRate).convert(to: carton / .week)
 print(weeklyCartons)  // Prints '350.0 carton/week'
 ```
 
-### Adding custom units to the Registry
-
-To support deserialization and runtime querying of available units, this package keeps a global registry of the default units. The `Unit.define` method does not insert new definitions into this registry. While this avoids conflicts and prevents race conditions, it also means that units created using `Unit.define` cannot be deserialized correctly or looked up using `Unit(fromSymbol:)`
-
-If these features are absolutely needed, and the implications are understood, custom units can be added to the registry using `Unit.register`:
-
-```swift
-let centifoot = try Unit.register(
-    name: "centifoot",
-    symbol: "cft",
-    dimension: [.Length: 1],
-    coefficient: 0.003048 // This is the conversion to meters
-)
-```
-
-Note that you may only register the unit once globally, and afterwards it should be accessed either by the assigned variable or using `Unit(fromSymbol: String)`.
-
-To simplify access, `Unit` may be extended with a static property:
-
-```swift
-extension Unit {
-    public static var centifoot = try! Unit.fromSymbol("cft")
-}
-
-let measurement = 5.measured(in: .centifoot)
-```
-
-Again, unless strictly necessary, `Unit.define` is preferred over `Unit.register`.
-
 ## CLI
 
 The easiest way to install the CLI is with brew:

Sources/CLI/Convert.swift

@@ -39,6 +39,8 @@ struct Convert: ParsableCommand {
     }
 }
 
+let registry = Units.Registry.default
+
 extension Expression: @retroactive ExpressibleByArgument {
     public convenience init?(argument: String) {
         let argument = argument.replacingOccurrences(of: "_", with: " ")
@@ -48,9 +50,9 @@ extension Expression: @retroactive ExpressibleByArgument {
 
 extension Units.Unit: @retroactive ExpressibleByArgument {
     public init?(argument: String) {
-        if let unit = try? Self(fromName: argument) {
+        if let unit = try? Self(fromName: argument, registry: registry) {
             self = unit
-        } else if let unit = try? Self(fromSymbol: argument) {
+        } else if let unit = try? Self(fromSymbol: argument, registry: registry) {
             self = unit
         } else {
             return nil

Sources/CLI/List.swift

@@ -7,7 +7,7 @@ struct List: ParsableCommand {
     )
 
     func run() throws {
-        let units = Units.Unit.allDefined().sorted { u1, u2 in
+        let units = registry.allUnits().sorted { u1, u2 in
             u1.name <= u2.name
         }
 

Sources/Units/Expression.swift

@@ -27,8 +27,8 @@ public final class Expression {
     /// - `5m^2/s + (1m + 2m)^2 / 5s`
     ///
     /// - Parameter expr: The string expression to parse.
-    public init(_ expr: String) throws {
-        let parsed = try Parser(expr).parseExpression()
+    public init(_ expr: String, registry: Registry = .default) throws {
+        let parsed = try Parser(expr, registry: registry).parseExpression()
         first = parsed.first
         last = parsed.last
         count = parsed.count

Sources/Units/Measurement/Measurement.swift

@@ -165,9 +165,9 @@ extension Measurement: CustomStringConvertible {
     }
 }
 
-extension Measurement: LosslessStringConvertible {
-    public init?(_ description: String) {
-        guard let parsed = try? Parser(description).parseMeasurement() else {
+public extension Measurement {
+    init?(_ description: String, registry _: Registry = .default) {
+        guard let parsed = try? Parser(description, registry: .default).parseMeasurement() else {
             return nil
         }
         value = parsed.value

Sources/Units/Parser.swift

@@ -1,6 +1,7 @@
 import Foundation
 
 class Parser {
+    var registry: Registry
     var data: [UnicodeScalar]
     var position = 0
 
@@ -18,8 +19,9 @@ class Parser {
         return Character(UnicodeScalar(data[position + 1]))
     }
 
-    init(_ string: String) {
+    init(_ string: String, registry: Registry) {
         data = Array(string.unicodeScalars)
+        self.registry = registry
     }
 
     func parseMeasurement() throws -> Measurement {
@@ -206,7 +208,7 @@ class Parser {
                 unitString.append(cur)
                 consume()
             }
-            let unit = try Unit(fromSymbol: unitString)
+            let unit = try Unit(fromSymbol: unitString, registry: registry)
             return .unit(unit)
         }
     }