public final class HealthUnit
- Object
- HealthUnit
A unit of measure for health data. Instances are interned constants, so
== is a valid identity test and is used throughout the API.
The symbol is the wire format
getSymbol() is public API rather than an internal detail because the
string genuinely has to cross the platform boundary: Apple’s
HKUnit(from:) parses exactly this syntax ("count/min", "kg",
"kcal", "mmHg", "degC", "mg/dL", "mL/(kg*min)"), so the iOS
port passes it straight through with no mapping table. The Android port
maps it to the matching androidx.health.connect.client.units type.
Making that contract visible and documented is better than smuggling it
through an implementation class.
Conversion
Conversion is affine (canonical = value * scale + offset) rather than
a simple ratio, because temperature needs the offset. Converting between
units of different dimensions throws IllegalArgumentException: that is
a bug in the calling code, not a condition to be reported through an
AsyncResource.
double lb = HealthUnit.convert(80, HealthUnit.KILOGRAM, HealthUnit.POUND);
Fields
Methods
public String getSymbol() | The unit symbol, in the exact syntax Apple’s HKUnit(from:) accepts. |
public HealthUnitDimension getDimension() | The physical dimension this unit measures. |
public boolean isCompatibleWith(HealthUnit other) | true when other measures the same dimension and a conversion between the two is therefore meaningful. |
public double toCanonical(double value) | Converts value, expressed in this unit, into the canonical unit of this unit’s dimension. |
public double fromCanonical(double value) | Converts value, expressed in the canonical unit of this unit’s dimension, into this unit. |
public static double convert(double value, HealthUnit from, HealthUnit to) | Converts a value between two units of the same dimension. |
public static HealthUnit forSymbol(String symbol) | Looks a unit up by its symbol, or null when the symbol is unknown to this version of the framework. |
public static List<HealthUnit> values() | Every unit known to this version of the framework. |
public String toString() | Returns getSymbol(), so string concatenation in log statements and error messages reads naturally. |
Inherited methods
Field details
COUNT
public static final HealthUnit COUNTA plain tally. Canonical unit of
HealthUnitDimension.COUNT.COUNT_PER_MINUTE
public static final HealthUnit COUNT_PER_MINUTEBeats, breaths or steps per minute. Canonical unit of
HealthUnitDimension.FREQUENCY.COUNT_PER_SECOND
public static final HealthUnit COUNT_PER_SECONDCounts per second.
PERCENT
public static final HealthUnit PERCENTA ratio expressed as a percentage. Canonical unit of
HealthUnitDimension.PERCENT. Note that HealthKit represents
oxygen saturation and body-fat percentage as 0..1 fractions
natively; the iOS port scales them into this unit.KILOGRAM
public static final HealthUnit KILOGRAMCanonical unit of
HealthUnitDimension.MASS.GRAM
public static final HealthUnit GRAMMILLIGRAM
public static final HealthUnit MILLIGRAMMICROGRAM
public static final HealthUnit MICROGRAMPOUND
public static final HealthUnit POUNDOUNCE
public static final HealthUnit OUNCESTONE
public static final HealthUnit STONEMETER
public static final HealthUnit METERCanonical unit of
HealthUnitDimension.LENGTH.KILOMETER
public static final HealthUnit KILOMETERCENTIMETER
public static final HealthUnit CENTIMETERMILE
public static final HealthUnit MILEFOOT
public static final HealthUnit FOOTINCH
public static final HealthUnit INCHYARD
public static final HealthUnit YARDKILOCALORIE
public static final HealthUnit KILOCALORIECanonical unit of
HealthUnitDimension.ENERGY. Kilocalories rather
than joules because it is the idiomatic unit on both platforms and
in every consumer health UI.KILOJOULE
public static final HealthUnit KILOJOULEJOULE
public static final HealthUnit JOULEMILLISECOND
public static final HealthUnit MILLISECONDCanonical unit of
HealthUnitDimension.TIME. Milliseconds because
heart-rate variability is reported in them and the rest of the API
speaks epoch millis.SECOND
public static final HealthUnit SECONDMINUTE
public static final HealthUnit MINUTEHOUR
public static final HealthUnit HOURMILLIMETER_OF_MERCURY
public static final HealthUnit MILLIMETER_OF_MERCURYCanonical unit of
HealthUnitDimension.PRESSURE.KILOPASCAL
public static final HealthUnit KILOPASCALDEGREE_CELSIUS
public static final HealthUnit DEGREE_CELSIUSCanonical unit of
HealthUnitDimension.TEMPERATURE.DEGREE_FAHRENHEIT
public static final HealthUnit DEGREE_FAHRENHEITFahrenheit.
C = F * 5/9 - 160/9, which is why HealthUnit
conversion carries an offset rather than being a plain ratio.LITER
public static final HealthUnit LITERCanonical unit of
HealthUnitDimension.VOLUME.MILLILITER
public static final HealthUnit MILLILITERFLUID_OUNCE_US
public static final HealthUnit FLUID_OUNCE_USCUP_US
public static final HealthUnit CUP_USWATT
public static final HealthUnit WATTCanonical unit of
HealthUnitDimension.POWER.METER_PER_SECOND
public static final HealthUnit METER_PER_SECONDCanonical unit of
HealthUnitDimension.VELOCITY.KILOMETER_PER_HOUR
public static final HealthUnit KILOMETER_PER_HOURMILE_PER_HOUR
public static final HealthUnit MILE_PER_HOURML_PER_KG_PER_MINUTE
public static final HealthUnit ML_PER_KG_PER_MINUTECanonical unit of
HealthUnitDimension.OXYGEN_UPTAKE; the standard
VO2-max unit. The symbol is the exact HKUnit spelling.MILLIMOLE_PER_LITER
public static final HealthUnit MILLIMOLE_PER_LITERCanonical unit of
HealthUnitDimension.GLUCOSE_CONCENTRATION; the
SI unit, used across most of the world.MILLIGRAM_PER_DECILITER
public static final HealthUnit MILLIGRAM_PER_DECILITERThe unit used clinically in the United States. The 18.0182 factor is
the molar mass of glucose – it is not a general mg/dL to mmol/L
conversion and must not be reused for another analyte.
Method details
getSymbol
public String getSymbol()The unit symbol, in the exact syntax Apple’s
HKUnit(from:)
accepts. See the class documentation for why this is public API.getDimension
public HealthUnitDimension getDimension()The physical dimension this unit measures.
isCompatibleWith
public boolean isCompatibleWith(HealthUnit other)true when other measures the same dimension and a conversion
between the two is therefore meaningful.toCanonical
public double toCanonical(double value)Converts
value, expressed in this unit, into the canonical unit of
this unit’s dimension.fromCanonical
public double fromCanonical(double value)Converts
value, expressed in the canonical unit of this unit’s
dimension, into this unit.convert
public static double convert(double value, HealthUnit from, HealthUnit to)Converts a value between two units of the same dimension.
Throws
IllegalArgumentException- if either unit is null or the two measure different dimensions. Crossing dimensions is a coding error and is surfaced as one.
forSymbol
public static HealthUnit forSymbol(String symbol)Looks a unit up by its symbol, or
null when the symbol is unknown
to this version of the framework. Total by design: a persisted
symbol read back by an older runtime yields null rather than an
exception.values
public static List<HealthUnit> values()Every unit known to this version of the framework.
toString
public String toString()Returns
getSymbol(), so string concatenation in log statements
and error messages reads naturally.