Type Method

unitFromString:

Returns the unit instance described by the provided string.

Declaration

+ (instancetype)unitFromString:(NSString *)string;

Parameters

string

A string representation of the unit. For example, count, kg, or m/s^2.

Return Value

The unit object described by the string. If the string does not represent a valid unit, this method throws an exception (NSInvalidArgumentException).

Discussion

You can create unit objects using a string representation of that unit. This is a convenient way to create complex, compound units. A few sample units are shown below.

HKUnit *count = [HKUnit unitFromString:@"count"];
HKUnit *mass = [HKUnit unitFromString:@"kg"];
HKUnit *acceleration = [HKUnit unitFromString:@"m/s^2"];

Unit strings use one or more characters to represent the International System of Units (SI). The unit strings for SI units are listed in Table 1 .

Table 1

SI units

Unit string

Name

Type

“g”

Grams

Mass

“m”

Meters

Length

“L” or “l”

Liters

Volume

“Pa”

Pascals

Pressure

“s”

Seconds

Time

“J”

Joules

Energy

“K”

Kelvin

Temperature

“S”

Siemens

Electrical conductance

“mol<molar mass

>” for example “mol<180.1558>”

Each SI unit can also take an optional prefix. Valid prefix strings are listed in Table 2.

Table 2

SI unit prefixes

Prefix string

Name

Multiplier

“p”

Pico-

1.0e-12

“n”

Nano-

1.0e-9

“mc”

Micro-

1.0e-6

“m”

Milli-

0.001

“c”

Centi-

0.01

“d”

Deci-

0.1

“da”

Deca-

10

“h”

Hecto-

100

“k”

Kilo-

1000

“M”

Mega-

1.0e6

"G”

Giga-

1.0e9

“T”

Tera-

1.0e12

The HKUnit class also supports a number of non-SI units. Valid non-SI units are shown in Table 3.

Table 3

Non-SI units

Unit string

Name

Type

“oz”

Ounces

Mass

“lb”

Pounds

Mass

“st”

Stones

Mass

“in”

Inches

Length

“ft”

Feet

Length

“mi”

Miles

Length

“mmHg”

Millimeters of mercury

Pressure

“cmAq”

Centimeters of water

Pressure

“atm”

Atmospheres

Pressure

“fl_oz_us”

US fluid ounces

Volume

“fl_oz_imp”

Imperial fluid ounces

Volume

“pt_us”

US pint

Volume

“pt_imp”

Imperial pint

Volume

“min”

Minutes

Time

“hr”

Hours

Time

“d”

Days

Time

“cal”

Calories

Energy

“kcal”

Kilocalories

Energy

“degC”

Degrees Celsius

Temperature

“degF”

Degrees Fahrenheit

Temperature

“count”

Count

Count

“%”

Percent

Percent

Of these, the count and percent units deserve special attention. Count units represent raw scalar values. They can be used to represent the number of times an event occurs—for example, the number of steps the user has taken or the number of times the user has used his or her inhaler. They can also be used as part of a compound unit—for example, the beats portion of beats per minute.

The percent unit measures a value between 0.0 and 1.0. HealthKit uses percent units when measuring body fat percentage, oxygen saturation, blood alcohol content, and similar values.

You can create more complex, compound units by mathematically combining multiple individual units. Unit strings can include symbols that indicate multiplication (. or *), division (/) or raising a unit to a power (^). In compound unit strings, multiplication is evaluated before anything else. Additionally, there can only be one division symbol in the string. Common compound units are shown in Table 4.

Table 4

Compound units in HealthKit

Sample type

Unit type

Unit name

Unit string

Heart rate

Count/time

Beats per minute

"count/min”

Blood glucose level

Mass/volume

Milligrams per deciliter

"mg/dl”

Heat flux

Energy/time

Joules per second

"J/s”

See Also

Working with Units

unitString

A string representation of the unit object.

- isNull

Returns a Boolean value indicating whether the unit is null.