Skip to content

Commit

Permalink
Enhances readme
Browse files Browse the repository at this point in the history
  • Loading branch information
NeedleInAJayStack committed Nov 8, 2021
1 parent 3823595 commit 97970c7
Showing 1 changed file with 25 additions and 6 deletions.
31 changes: 25 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,12 +5,23 @@ which are a numerical value with a unit of measure. It has been designed so that
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 imaginable. You want to convert `12 km³/hr/N` to
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!

## Getting Started

To start using units, simply import it to your project via the `Package.swift` file:

```swift
dependencies: [
.package(url: "https://github.com/NeedleInAJayStack/Units", from: "0.0.1"),
```

This package has no other dependencies.

## Usage

Users should interact primarily with Measurements. Here are a few usage examples:
Users should interact primarily with the `Measurement` struct. Here are a few usage examples:

```swift
let drivingSpeed = 60.measured(in: .mile / .hour)
Expand All @@ -21,6 +32,14 @@ let drivingDistance = drivingSpeed * drivingTime
print(drivingDistance.convert(to: .mile)) // Prints 30 mi
```

This packages type names closely match the unit system provided by `Foundation`. This was purposeful 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)
```

## Conversion

Only linear conversions are supported. The vast majority of unit conversions are simply changes in scale, represented by a single
Expand All @@ -33,8 +52,8 @@ Each quantity should have a single "base unit", through which the units of that
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
value should be what a base unit is multiplied by to result in the defined unit. For example, `kilometer` should have a coefficient
of `1000` because there are 1000 meters in 1 kilometer.
value should be what a base unit is multiplied by to result in one of the defined unit. For example, `kilometer` should have a
coefficient of `1000` because there are 1000 meters in 1 kilometer.

Defined units of complex quantities (`horsepower`, for example) must have coefficients that convert to the SI unit of that dimension.
That is, `horsepower` should have a conversion to `kilogram * meter^2 / second^2` (otherwise known as `watt`)
Expand All @@ -52,7 +71,7 @@ the `*`, `/`, or `^` characters because those are used in the symbol representat

## Custom Units

To support serialization, Unit is backed by a global registry which is populated with many values by default. However,
To support serialization, Unit is backed by a global registry which is populated with many units by default. However,
you may add your own custom units to this registry using the `Unit.define` function.

```swift
Expand All @@ -77,7 +96,7 @@ extension Unit {
let measurement = Measurement(value: 5, unit: .centifoot)
```

## To Do:
## Future Development Tasks:

- Add more defined units
- Allow user-defined quantities

0 comments on commit 97970c7

Please sign in to comment.