Returns the unit instance described by the provided string.
- iOS 8.0+
- Mac Catalyst 13.0+
- watchOS 2.0+
A string representation of the unit, such as
The unit object described by the string. If the string does not represent a valid unit, this method throws an exception (
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.
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 .
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
Each SI unit can also take an optional prefix. Valid prefix strings are listed in Table 2.
HKUnit class also supports a number of non-SI units, as shown in Table 3.
Millimeters of mercury
Centimeters of water
U.S. fluid ounces
Imperial fluid ounces
Decibel: Sound Pressure Level
Decibel: Hearing Level
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.
Beats per minute
Milligrams per deciliter
Blood glucose level
Milliliters per kilogram per minute
Volume/(mass * time)
Liters per minute
Peak Expiratory Flow Rate