Skip to content

Measurement addition and subtraction support dimensionally equivalent units #17

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
NeedleInAJayStack merged 4 commits into from
May 12, 2025
Merged

Measurement addition and subtraction support dimensionally equivalent units #17

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a9ab907
docs: Adds homebrew to install instructions
NeedleInAJayStack May 12, 2025
a9bc961
chore: Format
NeedleInAJayStack May 12, 2025
2a02e76
feat: Add/Subtract support dimensionally equivalent units
NeedleInAJayStack May 12, 2025
cf97e6b
doc: Removes unnecessary newlines from readme
NeedleInAJayStack May 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 29 additions & 54 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

Expand All @@ -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)
Expand All @@ -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)
Expand Down Expand Up @@ -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:

Expand All @@ -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. ` * `
Expand All @@ -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

Expand All @@ -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(
Expand Down Expand Up @@ -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(
Expand All @@ -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:

Expand All @@ -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
Expand All @@ -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:

Expand All @@ -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!
45 changes: 22 additions & 23 deletions Sources/Units/Expression.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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())
Expand All @@ -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 {
Expand All @@ -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 {
Expand All @@ -102,7 +101,7 @@ public final class Expression {
left = next.node
}
try exponentiate(node: left)

// Multiplication
left = first
while let next = left.next {
Expand All @@ -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
Expand All @@ -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")
}
Expand Down Expand Up @@ -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)
}
}

Expand All @@ -216,7 +215,7 @@ extension ExpressionNode: Equatable {
enum ExpressionNodeValue {
case measurement(Measurement)
case subExpression(Expression)

func copy() -> ExpressionNodeValue {
switch self {
case let .measurement(measurement):
Expand Down Expand Up @@ -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
Expand Down
Loading