read

If you use units and quantities in your app, HealthKit will be very useful.

This guide will only show how to handle for length. But the same API works for mass, volume, time, energy etc (relevant to Health app).

HealthKit

There are 2 classes provided by HealthKit which you can use:

1. HKUnit
2. HKQuantity

For example, to represent 1.2345 meter:

let meterUnit = HKUnit.meterUnit()
let m = HKQuantity(unit: meterUnit, doubleValue: 1.2345)

It is a 2 step process. First to create the meterUnit (because, length could have unit as centimeter/foot/etc). Then create the quantity with the unit and the amount as a double.

Unit Conversions

With a HKQuantity object, you can get the amount:

// Return 1.2345 (m)
m.doubleValueForUnit(meterUnit)

// In centimeter - create meter unit with the prefix .Centi
let cmUnit = HKUnit.meterUnitWithMetricPrefix(.Centi)
// Return 123.45 (cm)
m.doubleValueForUnit(cmUnit)

// In foot
let footUnit = HKUnit.footUnit()
// Return 4.0501968503937 (feet)
m.doubleValueForUnit(footUnit)

As you can see, you always have to provide the HKUnit, even if you created the quantity with the meterUnit at first. The nice thing is that unit conversions is provided by the framework.

Formatters

To display the unit and quantity, it is best to use a formatter.

A formatter will take care of localization and stuff, which is complex for different part of the world.

For length, we will use NSLengthFormatter. There are others for mass, energy, etc. Not all formatters are provided at the moment eg. Volume formatter is missing.

This is how you configure the formatter:

let formatter = NSLengthFormatter()
formatter.forPersonHeightUse = true
formatter.unitStyle = .Medium

With the formatter, you can get the string from a HKQuantity object:

let lengthFormatterUnit: NSLengthFormatterUnit = HKUnit.lengthFormatterUnitFromUnit(meterUnit)
let value = m.doubleValueForUnit(meterUnit)
// Returns "1.2345 m"
formatter.stringFromValue(value, unit: lengthFormatterUnit)

Note: The first line of code is to get the NSLengthFormatterUnit(another unit object from Foundation’s NSLengthFormatter class) from meterUnit (HealthKit unit object). Don’t be confused with the 2 unit classes.

Number Formatter

We have learnt how to print 1.2345 m.

But how do you print to eg. 2 decimal places, or 3 significant figures?

You can can do so by configuring the NSNumberFormatter which is a property of the NSLengthFormatter.

formatter.numberFormatter.maximumSignificantDigits = 3
formatter.numberFormatter.maximumFractionDigits = 3     // decimal places

// Returns "1.23 m"
formatter.stringFromValue(value, unit: lengthFormatterUnit)