Merge pull request #17 from NeedleInAJayStack/feat/add-dimensionally-equivalent-units

Author: NeedleInAJayStack

README.md

@@ -1,12 +1,8 @@
 # Units 📏
 
-Units is a Swift package to manipulate, compare, and convert between physical quantities. This package models measurements, 
-which are a numerical value with a unit of measure. It has been designed so that users don't need to worry whether they are 
-using a defined unit (like `Newton`) or a complex composite unit (like `kg*m/s^2`). Both should be easy to convert to and from
-different units, perform arithmetic operations, check dimensionality, or serialize to and from a string format.
+Units is a Swift package to manipulate, compare, and convert between physical quantities. This package models measurements, which are a numerical value with a unit of measure. It has been designed so that users don't need to worry whether they are using a defined unit (like `Newton`) or a complex composite unit (like `kg*m/s^2`). Both should be easy to convert to and from different units, perform arithmetic operations, check dimensionality, or serialize to and from a string format.
 
-This approach allows us to easily handle any permutation of units. You want to convert `12 km³/hr/N` to 
-`ft²*s/lb`? We've got you covered!
+This approach allows us to easily handle any permutation of units. You want to convert `12 km³/hr/N` to `ft²*s/lb`? We've got you covered!
 
 Included is a convenient command-line tool for performing quick unit conversions. See the [CLI section](#cli) for details.
 
@@ -23,7 +19,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,9 +30,9 @@ let drivingDistance = drivingSpeed * drivingTime
 print(drivingDistance.convert(to: .mile)) // Prints 30 mi
 ```
 
-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:
+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:
 
 ```swift
 let measurement = Units.Measurement(value: 5, unit: .mile)
@@ -72,41 +68,25 @@ print(distance)  // Prints '15 m/s'
 
 ## Conversion
 
-Only linear conversions are supported. The vast majority of unit conversions are simply changes in scale, represented by a single
-conversion coefficient, sometimes with a constant shift. Units that don't match this format (like currency conversions, which are
-typically time-based functions) are not supported.
+Only linear conversions are supported. The vast majority of unit conversions are simply changes in scale, represented by a single conversion coefficient, sometimes with a constant shift. Units that don't match this format (like currency conversions, which are typically time-based functions) are not supported.
 
-Composite units are those that represent complex quantities and dimensions. A good example is `horsepower`, whose quantity is 
-`mass * length^2 / time^2`.
+Composite units are those that represent complex quantities and dimensions. A good example is `horsepower`, whose quantity is `mass * length^2 / time^2`.
 
 ### Coefficients
 
-Each quantity has a single "base unit", through which the units of that quantity may be converted. SI units have been
-chosen to be these base units for all quantities.
+Each quantity has a single "base unit", through which the units of that quantity may be converted. SI units have been chosen to be these base units for all quantities.
 
-Non-base units require a conversion coefficient to convert between them and other units of the same dimension. This coefficient
-is the number of base units there are in one of the defined unit. For example, `kilometer` has a coefficient of `1000` 
-because there are 1000 meters in 1 kilometer.
+Non-base units require a conversion coefficient to convert between them and other units of the same dimension. This coefficient is the number of base units there are in one of the defined unit. For example, `kilometer` has a coefficient of `1000` because there are 1000 meters in 1 kilometer.
 
-Composite units must have a coefficient that converts to the composte SI units of those dimensions. That is, `horsepower` should 
-have a conversion to `kilogram * meter^2 / second^2` (otherwise known as `watt`). This is natural for SI quantities and units, but
-care should be taken that a single, absolute base unit is chosen for all non-SI quantities since they will impact all composite 
-conversions.
+Composite units must have a coefficient that converts to the composte SI units of those dimensions. That is, `horsepower` should have a conversion to `kilogram * meter^2 / second^2` (otherwise known as `watt`). This is natural for SI quantities and units, but care should be taken that a single, absolute base unit is chosen for all non-SI quantities since they will impact all composite conversions.
 
 ### Constants
 
-Units that include a constant value, such as Fahrenheit, cannot be used within composite unit conversions. For example,
-you may not convert `5m/°F` to `m/°C` because its unclear how to handle their shifted scale. Instead use the 
-non-shifted Kelvin and Rankine temperature units to refer to temperature differentials.
+Units that include a constant value, such as Fahrenheit, cannot be used within composite unit conversions. For example, you may not convert `5m/°F` to `m/°C` because its unclear how to handle their shifted scale. Instead use the non-shifted Kelvin and Rankine temperature units to refer to temperature differentials.
 
 ## Serialization
 
-Each defined unit must have a unique symbol, which is used to identify and serialize/deserialize it. Defined unit symbols are not
-allowed to contain the `*`, `/`, `^`, or ` ` characters because those are used in the symbol representation of complex units.
-Complex units are represented by their arithmetic combination of simple units using `*` for multiplication, `/` for division,
-and `^` for exponentiation. Order of operations treats exponentiation first, and multiplication and division equally, from left-
-to-right. This means that, unless negatively exponentiated, units following a `*` can always be considered to be "in the numerator",
-and those following `/` can always be considered to be "in the denominator".
+Each defined unit must have a unique symbol, which is used to identify and serialize/deserialize it. Defined unit symbols are not allowed to contain the `*`, `/`, `^`, or ` ` characters because those are used in the symbol representation of complex units. Complex units are represented by their arithmetic combination of simple units using `*` for multiplication, `/` for division, and `^` for exponentiation. Order of operations treats exponentiation first, and multiplication and division equally, from left-to-right. This means that, unless negatively exponentiated, units following a `*` can always be considered to be "in the numerator", and those following `/` can always be considered to be "in the denominator".
 
 Here are a few examples:
 
@@ -125,7 +105,7 @@ Expressions are a mathematical combination of measurements. Arithemetic operator
 - `5.3 m + 3.8 m`
 - `5m^2/s + (1m + 2m)^2 / 5s`
 
-There are few expression parsing rules to keep in mind: 
+There are few expression parsing rules to keep in mind:
 
 - All parentheses must be matched
 - All measurement operators must have a leading and following space. i.e. ` * `
@@ -134,8 +114,7 @@ There are few expression parsing rules to keep in mind:
 
 ## Default Units
 
-For a list of the default units and their conversion factors, see the
-[`DefaultUnits.swift file`](https://github.com/NeedleInAJayStack/Units/blob/main/Sources/Units/Unit/DefaultUnits.swift)
+For a list of the default units and their conversion factors, see the [`DefaultUnits.swift file`](https://github.com/NeedleInAJayStack/Units/blob/main/Sources/Units/Unit/DefaultUnits.swift)
 
 ## Custom Units
 
@@ -157,8 +136,7 @@ This returns a Unit object that can be used in arithmetic, conversions, and seri
 
 ### 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:
+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(
@@ -197,13 +175,9 @@ 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:)` 
+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`:
+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(
@@ -214,8 +188,7 @@ let centifoot = try Unit.register(
 )
 ```
 
-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)`.
+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:
 
@@ -231,8 +204,14 @@ Again, unless strictly necessary, `Unit.define` is preferred over `Unit.register
 
 ## CLI
 
-The command-line interface can be built and installed by running the command below. Note that 
-[swift](https://www.swift.org/download/) must be installed.
+The easiest way to install the CLI is with brew:
+
+```sh
+brew tap NeedleInAJayStack/tap
+brew install units
+```
+
+Alternatively, you can build it from source and install it to `/usr/local/bin/` using the install script. Note that [swift](https://www.swift.org/download/) must be installed, and you need write permissions to `/usr/local/bin/`.
 
 ```bash
 ./install.sh
@@ -252,9 +231,7 @@ You can then perform unit conversions using the `unit convert` command:
 unit convert 5m/s mi/hr  # Returns 11.184681460272012 mi/hr
 ```
 
-This command uses the unit and expression [serialization format](#serialization). Note that for
-convenience, you may use an underscore `_` to represent the normally serialized space. Also,
-`*` characters may need to be escaped.
+This command uses the unit and expression [serialization format](#serialization). Note that for convenience, you may use an underscore `_` to represent the normally serialized space. Also, `*` characters may need to be escaped.
 
 You can also evaulate math in the first argument. For example:
 
@@ -272,6 +249,4 @@ unit list
 
 ## Contributing
 
-Contributions are absolutely welcome! If you find yourself using a custom unit a lot, feel free
-to stick it in an MR, and we can add it to the default list!
-
+Contributions are absolutely welcome! If you find yourself using a custom unit a lot, feel free to stick it in an MR, and we can add it to the default list!

Sources/Units/Expression.swift

@@ -2,17 +2,17 @@
 public final class Expression {
     // Implemented as a linked list of ExpressionNodes. This allows us to indicate operators,
     // and iteratively solve by reducing the list according to the order of operations.
-    
+
     var first: ExpressionNode
     var last: ExpressionNode
     var count: Int
-    
+
     init(node: ExpressionNode) {
-        self.first = node
-        self.last = node
+        first = node
+        last = node
         count = 1
     }
-    
+
     /// Initializes an expression from a string.
     ///
     /// Parsing rules:
@@ -29,25 +29,25 @@ public final class Expression {
     /// - Parameter expr: The string expression to parse.
     public init(_ expr: String) throws {
         let parsed = try Parser(expr).parseExpression()
-        self.first = parsed.first
-        self.last = parsed.last
-        self.count = parsed.count
+        first = parsed.first
+        last = parsed.last
+        count = parsed.count
     }
-    
+
     /// Reduces the expression to a single measurement, respecting the [order of operations](https://en.wikipedia.org/wiki/Order_of_operations)
     public func solve() throws -> Measurement {
         let copy = self.copy()
         return try copy.computeAndDestroy()
     }
-    
+
     @discardableResult
     func append(op: Operator, node: ExpressionNode) -> Self {
         last.next = .init(op: op, node: node)
         last = node
         count = count + 1
         return self
     }
-    
+
     func copy() -> Expression {
         // Copy the expression list so the original is not destroyed
         let copy = Expression(node: first.copy())
@@ -58,12 +58,11 @@ public final class Expression {
         }
         return copy
     }
-    
+
     /// Reduces the expression to a single measurement, respecting the [order of operations](https://en.wikipedia.org/wiki/Order_of_operations)
     ///
     /// NOTE: This flattens the list, destroying it. Use `solve` for non-destructive behavior.
     private func computeAndDestroy() throws -> Measurement {
-        
         // SubExpressions
         func computeSubExpression(node: ExpressionNode) throws {
             switch node.value {
@@ -81,7 +80,7 @@ public final class Expression {
         }
         try computeSubExpression(node: left)
         // At this point, there should be no more sub expressions
-        
+
         // Exponentals
         func exponentiate(node: ExpressionNode) throws {
             guard let exponent = node.exponent else {
@@ -102,7 +101,7 @@ public final class Expression {
             left = next.node
         }
         try exponentiate(node: left)
-        
+
         // Multiplication
         left = first
         while let next = left.next {
@@ -123,15 +122,15 @@ public final class Expression {
                 fatalError("Parentheses still present during multiplication phase")
             }
         }
-        
+
         // Addition
         left = first
         while let next = left.next {
             let right = next.node
             switch (left.value, right.value) {
             case let (.measurement(leftMeasurement), .measurement(rightMeasurement)):
                 switch next.op {
-                case .add:  // Compute and absorb right node into left
+                case .add: // Compute and absorb right node into left
                     left.value = try .measurement(leftMeasurement + rightMeasurement)
                     left.next = right.next
                 case .subtract: // Compute and absorb right node into left
@@ -144,7 +143,7 @@ public final class Expression {
                 fatalError("Parentheses still present during addition phase")
             }
         }
-        
+
         if first.next != nil {
             fatalError("Expression list reduction not complete")
         }
@@ -194,15 +193,15 @@ class ExpressionNode {
     var value: ExpressionNodeValue
     var exponent: Int?
     var next: ExpressionLink?
-    
+
     init(_ value: ExpressionNodeValue, exponent: Int? = nil, next: ExpressionLink? = nil) {
         self.value = value
         self.exponent = exponent
         self.next = next
     }
-    
+
     func copy() -> ExpressionNode {
-        return .init(value.copy(), exponent: self.exponent)
+        return .init(value.copy(), exponent: exponent)
     }
 }
 
@@ -216,7 +215,7 @@ extension ExpressionNode: Equatable {
 enum ExpressionNodeValue {
     case measurement(Measurement)
     case subExpression(Expression)
-    
+
     func copy() -> ExpressionNodeValue {
         switch self {
         case let .measurement(measurement):
@@ -254,7 +253,7 @@ extension ExpressionNodeValue: Equatable {
 class ExpressionLink {
     let op: Operator
     let node: ExpressionNode
-    
+
     init(op: Operator, node: ExpressionNode) {
         self.op = op
         self.node = node