11# Units 📏
22
3- Units is a Swift package to manipulate, compare, and convert between physical quantities. This package models measurements,
4- 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
3+ Units is a Swift package to manipulate, compare, and convert between physical quantities. This package models measurements,
4+ 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
55using a defined unit (like ` Newton ` ) or a complex composite unit (like ` kg*m/s^2 ` ). Both should be easy to convert to and from
66different units, perform arithmetic operations, check dimensionality, or serialize to and from a string format.
77
8- This approach allows us to easily handle any permutation of units. You want to convert ` 12 km³/hr/N ` to
8+ This approach allows us to easily handle any permutation of units. You want to convert ` 12 km³/hr/N ` to
99` ft²*s/lb ` ? We've got you covered!
1010
1111Included is a convenient command-line tool for performing quick unit conversions. See the [ CLI section] ( #cli ) for details.
@@ -34,8 +34,8 @@ let drivingDistance = drivingSpeed * drivingTime
3434print (drivingDistance.convert (to : .mile )) // Prints 30 mi
3535```
3636
37- The type names in this package align closely with the unit system provided by ` Foundation ` . This was intentional to provide a
38- familiar nomenclature for Swift developers. The APIs have been designed to avoid namespace ambiguity in files where both ` Units `
37+ The type names in this package align closely with the unit system provided by ` Foundation ` . This was intentional to provide a
38+ familiar nomenclature for Swift developers. The APIs have been designed to avoid namespace ambiguity in files where both ` Units `
3939and ` Foundation ` are imported as much as possible. However, if an issue arises, just qualify the desired package like so:
4040
4141``` swift
@@ -76,7 +76,7 @@ Only linear conversions are supported. The vast majority of unit conversions are
7676conversion coefficient, sometimes with a constant shift. Units that don't match this format (like currency conversions, which are
7777typically time-based functions) are not supported.
7878
79- Composite units are those that represent complex quantities and dimensions. A good example is ` horsepower ` , whose quantity is
79+ Composite units are those that represent complex quantities and dimensions. A good example is ` horsepower ` , whose quantity is
8080` mass * length^2 / time^2 ` .
8181
8282### Coefficients
@@ -85,18 +85,18 @@ Each quantity has a single "base unit", through which the units of that quantity
8585chosen to be these base units for all quantities.
8686
8787Non-base units require a conversion coefficient to convert between them and other units of the same dimension. This coefficient
88- is the number of base units there are in one of the defined unit. For example, ` kilometer ` has a coefficient of ` 1000 `
88+ is the number of base units there are in one of the defined unit. For example, ` kilometer ` has a coefficient of ` 1000 `
8989because there are 1000 meters in 1 kilometer.
9090
91- Composite units must have a coefficient that converts to the composte SI units of those dimensions. That is, ` horsepower ` should
91+ Composite units must have a coefficient that converts to the composte SI units of those dimensions. That is, ` horsepower ` should
9292have a conversion to ` kilogram * meter^2 / second^2 ` (otherwise known as ` watt ` ). This is natural for SI quantities and units, but
93- care should be taken that a single, absolute base unit is chosen for all non-SI quantities since they will impact all composite
93+ care should be taken that a single, absolute base unit is chosen for all non-SI quantities since they will impact all composite
9494conversions.
9595
9696### Constants
9797
9898Units that include a constant value, such as Fahrenheit, cannot be used within composite unit conversions. For example,
99- you may not convert ` 5m/°F ` to ` m/°C ` because its unclear how to handle their shifted scale. Instead use the
99+ you may not convert ` 5m/°F ` to ` m/°C ` because its unclear how to handle their shifted scale. Instead use the
100100non-shifted Kelvin and Rankine temperature units to refer to temperature differentials.
101101
102102## Serialization
@@ -125,7 +125,7 @@ Expressions are a mathematical combination of measurements. Arithemetic operator
125125- ` 5.3 m + 3.8 m `
126126- ` 5m^2/s + (1m + 2m)^2 / 5s `
127127
128- There are few expression parsing rules to keep in mind:
128+ There are few expression parsing rules to keep in mind:
129129
130130- All parentheses must be matched
131131- All measurement operators must have a leading and following space. i.e. ` * `
@@ -200,7 +200,7 @@ print(weeklyCartons) // Prints '350.0 carton/week'
200200To support deserialization and runtime querying of available units, this package keeps a global
201201registry of the default units. The ` Unit.define ` method does not insert new definitions into this
202202registry. While this avoids conflicts and prevents race conditions, it also means that units created
203- using ` Unit.define ` cannot be deserialized correctly or looked up using ` Unit(fromSymbol:) `
203+ using ` Unit.define ` cannot be deserialized correctly or looked up using ` Unit(fromSymbol:) `
204204
205205If these features are absolutely needed, and the implications are understood, custom units can be
206206added to the registry using ` Unit.register ` :
@@ -214,7 +214,7 @@ let centifoot = try Unit.register(
214214)
215215```
216216
217- Note that you may only register the unit once globally, and afterwards it should be accessed
217+ Note that you may only register the unit once globally, and afterwards it should be accessed
218218either by the assigned variable or using ` Unit(fromSymbol: String) ` .
219219
220220To simplify access, ` Unit ` may be extended with a static property:
@@ -231,8 +231,15 @@ Again, unless strictly necessary, `Unit.define` is preferred over `Unit.register
231231
232232## CLI
233233
234- The command-line interface can be built and installed by running the command below. Note that
235- [ swift] ( https://www.swift.org/download/ ) must be installed.
234+ The easiest way to install the CLI is with brew:
235+
236+ ``` sh
237+ brew tap NeedleInAJayStack/tap
238+ brew install units
239+ ```
240+
241+ Alternatively, you can build it from source and install it to ` /usr/local/bin/ ` using the install script. Note that
242+ [ swift] ( https://www.swift.org/download/ ) must be installed, and you need write permissions to ` /usr/local/bin/ ` .
236243
237244``` bash
238245./install.sh
@@ -274,4 +281,3 @@ unit list
274281
275282Contributions are absolutely welcome! If you find yourself using a custom unit a lot, feel free
276283to stick it in an MR, and we can add it to the default list!
277-
0 commit comments