Select Page
Latest 4.0.0 https://github.com/michalkonturek/MKUnits MIT ios 8.0 Michal Konturek

MKUnits is extremely precise unit conversion library for `Swift`. It provides units of measurement of physical quantities and simplifies manipulation of them.

NB For `Objective-C` implementation, please refer to MKUnits pod 2.2.1 or visit archived branch.

MKUnits is available under the MIT license. See the LICENSE file for more info.

## Installation

MKUnits is available through CocoaPods. To install
it, simply add the following line to your Podfile:

``pod "MKUnits"``

## Example

Let’s create 1.5 kilograms [kg],

``let kilograms = 1.5.kilogram()``

0.5 [kg] in grams [g]

``let grams = 500.gram()``

and 10 pounds [lb] (which is 4.5359237 [kg])

``let pounds = 10.pound()``

Then we add all of the above togehter and subtract 0.0001 [kg] in milligrams [mg].

``````let milligrams = 100.milligram()
var result = kilograms + grams + pounds - milligrams``````

The result amount is 6.5358237 [kg].

Now we subtract 0.5358237 [kg] in ounces [oz], which is 18.900624805 [oz] according to Google converter, but as MKUnits is very precise, it is in fact 18.900624805483390296005199558361177 [oz].

``````let ounces = 0.5358237.kilogram().converted(MassUnit.ounce)
result = result - ounces``````

The result amount is ~6 [kg]; 6.00000000000000000000000000000000003 [kg] to be exact.

Now we want the result to be in stones [st], so:

``````result = result.converted(MassUnit.stone)
// 0.94483873964811055873038869091017890993 st``````

As the result is too precise for our needs, we want to round it.

``````let rounded = result.rounded(3)
// 0.945 st``````

## Supported Units

At the moment MKUnits supports the following `group units`:

• Area (base unit: square meter)
• Mass (base unit: kilogram)
• Length (base unit: meter)
• Time (base unit: second)
• Volume (base unit: litre)

You can easily extend MKUnits by adding new `group units` or `units`.

## Extending MKUnits

### Adding a new `group unit`

To add a new `group unit`, simply create a class that extends `Unit` and follow the convention below.

Please make sure that `unit symbols` are unique across your new `group unit`.

``````
public final class NewUnit: Unit {

public static var unitA: NewUnit {
return NewUnit(
name: "unit A",
symbol: "uA",
ratio: NSDecimalNumber.one() // as it is a base unit
)
}

public static var unitB: NewUnit {
return NewUnit(
name: "unit B",
symbol: "uB",
ratio: NSDecimalNumber(mantissa: 2, exponent: 0, isNegative: false)
)
}
}

extension NSNumber {

public func unitA() -> Quantity {
return Quantity(amount: self, unit: NewUnit.unitA)
}

public func unitB() -> Quantity {
return Quantity(amount: self, unit: NewUnit.unitB)
}
}``````

### Adding new units to existing `group unit`

To add additional units to existing `group unit` simply create a category for that `group unit`.

Do not sublcass as units are only interconvertible with units belonging to the same `group unit`.

``````
extension NewUnit {
public static var unitC: NewUnit {
return NewUnit(
name: "unit C",
symbol: "uC",
ratio: NSDecimalNumber(mantissa: 4, exponent: 0, isNegative: false)
)
}
}

extension NSNumber {
public func unitC() -> Quantity {
return Quantity(amount: self, unit: NewUnit.unitC)
}
}``````

## Contributing

1. Fork it.
2. Create your feature branch (`git checkout -b new-feature`).
3. Commit your changes (`git commit -am 'Added new-feature'`).
4. Push to the branch (`git push origin new-feature`).
5. Create new Pull Request.

### Latest podspec

```{
"name": "MKUnits",
"version": "4.0.0",
"summary": "Unit conversion library for Swift. It provides units of measurement of physical quantities and simplifies manipulation of them.",
"homepage": "https://github.com/michalkonturek/MKUnits",
"type": "MIT",
},
"authors": {
"Michal Konturek": "[email protected]"
},
"source": {
"git": "https://github.com/michalkonturek/MKUnits.git",
"tag": "4.0.0"
},