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, such as 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, which 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

String

Unit name

Unit 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>

Moles

Mass

For molar mass, you must include the molar mass (in g/mol) of the item to be weighed. For example, for blood glucose samples, use mol<180.15588000005408>.

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

Table 2

SI unit prefixes

Prefix

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, as shown in Table 3.

Table 3

Non-SI units

String

Unit name

Unit type

oz

Ounces

Mass

lb

Pounds

Mass

st

Stones

Mass

in

Inches

Length

ft

Feet

Length

yd

Yard

Length

mi

Miles

Length

mmHg

Millimeters of mercury

Pressure

cmAq

Centimeters of water

Pressure

atm

Atmospheres

Pressure

fl_oz_us

U.S. fluid ounces

Volume

fl_oz_imp

Imperial fluid ounces

Volume

cup_us

U.S. cup

Volume

cup_imp

Imperial cup

Volume

pt_us

U.S. pint

Volume

pt_imp

Imperial pint

Volume

min

Minutes

Time

hr

Hours

Time

d

Days

Time

Hz

Hertz

Frequency

cal

Small calories

Energy

Cal

Large calories

Energy

kcal

Kilocalories

Energy

degC

Degrees Celsius

Temperature

degF

Degrees Fahrenheit

Temperature

dBASPL

Decibel: Sound Pressure Level

Sound pressure

dBHL

Decibel: Hearing Level

Sound pressure

IU

International Unit

Dosage

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 their 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

String

Unit name

Unit type

Sample type

count/min

Beats per minute

Count/time

Heart rate

mg/dl

Milligrams per deciliter

Mass/volume

Blood glucose level

ml/(kg*min)

Milliliters per kilogram per minute

Volume/(mass * time)

VO2 Max

L/min

Liters per minute

Volume/time

Peak Expiratory Flow Rate

See Also

Working with Units

unitString

A string representation of the unit object.

- isNull

Returns a Boolean value indicating whether the unit is null.