fling_units library

A type-safe measurement framework.

This library is intended for any application that requires manipulating measurements of any sort, e.g. distance or time. The measurements themselves are abstracted into different types, allowing them to be interpreted in any way required by the consumer. This allows for type safety across the measurement types as well as simplification of business logic in most cases.

The library uses the following vocabulary:

  • measurement: A value associated with a unit and a precision, e.g. "32.5 meters".
  • unit: A way to interpret a measurement, e.g. "kilometers" and "miles" are valid units for a Distance measurement.
  • interpret: A measurement is an abstract concept until it is interpreted with a specific unit in mind, at which point it can be represented as a number and that unit (e.g. "3.2 miles").
  • precision: The quality of a measurement, from the standpoint of significant digits.

Consider a ride-sharing app that aggregates ride information across several platforms. It may want to compare the distances for each potential driver from the client, but each source might provide that information in a different way. By reading the information from each source into an instance of Distance, the rest of our app can treat all sources the same way.

(The following example uses completely made-up APIs for Uber and Lyft.)

Distance uberDistance = Distance.miles(Uber.getDriverDistance(clientLocation));
Distance lyftDistance = Distance.kilometers(lyft.getNearestDriver(clientLocation).distanceInKm());

Instances of measurements such as Distance can be compared directly, without needing to convert beforehand. Further, they can be interpreted in any valid unit for their dimension at any time, without needing to know how they were created.

if (driverDistance < Distance.miles(0.5)) {
  print('Your driver is only ${driverDistance.feet} feet away!');
} else {
  print('Your driver is only ${driverDistance.miles} miles away!');
}

While the library strives to support all basic measurement units, not all "derived" units will be available. You can define arbitrary derived units yourself, e.g. "fuel economy" (distance divided by volume, e.g. miles per gallon), using the DerivedMeasurement type. Similarly, if a conversion is missing from the library (or you just want to make up your own unit), you can easily define it as a function that accepts a measurement and produces a double.

var fuelEconomy = DerivedMeasurement<Distance, Volume>(
  Distance.miles(150),
  Volume.gallons(5)
);
double kilometersPerLiter = fuelEconomy.as(Distance.asKilometers, Volume.asLiters);
double googaligadsPerLiter = fuelEconomy.as((distance) => distance.miles * 0.123, Volume.asLiters);

Finally, all measurements may be assigned a Precision to quantify the precision of the measurement instrument used. This prevents the measurements giving answers with more precision than they realistically could, and also mitigates some rounding errors in the implementation of the language itself.

Distance.miles(3.0, precision: 2).kilometers; // 4.8, not 4.82803...

Classes

Angle
AngleMeasurement
AngleUnit
Charge
ChargeMeasurement
ChargeUnit
DerivedUnit1<P extends UnitPosition<D>, D extends Dimension>
A derived Unit that has a single component.
DerivedUnit2<P1 extends UnitPosition<D1>, P2 extends UnitPosition<D2>, D1 extends Dimension, D2 extends Dimension>
A derived Unit that has two components.
DerivedUnit3<P1 extends UnitPosition<D1>, P2 extends UnitPosition<D2>, P3 extends UnitPosition<D3>, D1 extends Dimension, D2 extends Dimension, D3 extends Dimension>
A derived Unit that has three components.
Dimension
Dimension1<P extends UnitPosition<Dimension>>
Dimension2<P1 extends UnitPosition<Dimension>, P2 extends UnitPosition<Dimension>>
Dimension3<P1 extends UnitPosition<Dimension>, P2 extends UnitPosition<Dimension>, P3 extends UnitPosition<Dimension>>
Distance
DistanceMeasurement
DistanceUnit
Luminosity
LuminosityMeasurement
LuminosityUnit
Mass
MassMeasurement
MassUnit
Measurement<D extends Dimension>
Base class for any type of measurement.
MeasurementDot<N extends Measurement<D>, D extends Dimension>
MeasurementPer<N extends Measurement<D>, D extends Dimension>
MeasurementPrefix
NumExtension
Wrapper class for extensions on num types.
Precision
Represents the amount of precision for a measurement.
PrefixedMeasurementDot<N extends Measurement<D>, D extends Dimension>
PrefixedMeasurementPer<N extends Measurement<D>, D extends Dimension>
PrefixedUnitDot<N extends Unit<D>, D extends Dimension>
PrefixedUnitPer<N extends Unit<D>, D extends Dimension>
Pressure
PressureMeasurement
PressureUnit
Quantity
QuantityMeasurement
QuantityUnit
RoundingUnit<D extends Dimension>
A Unit that rounds its results to ints.
Temperature
Represents a "thermometer" temperature.
TemperatureChange
TemperatureChangeMeasurement
TemperatureChangeUnit
Time
TimeMeasurement
TimeUnit
Unit<D extends Dimension>
Interprets a measurement as a specific unit.
UnitDenominator<D extends Dimension>
Represents a unit in the denominator of a derived unit equation.
UnitDot<N extends Unit<D>, D extends Dimension>
UnitNumerator<D extends Dimension>
Represents a unit in the numerator of a derived unit equation.
UnitPer<N extends Unit<D>, D extends Dimension>
UnitPosition<D extends Dimension>
Represents the position of a unit in a derived unit equation.

Constants

amperes → const ChargeUnit
arcMinutes → const AngleUnit
arcSeconds → const AngleUnit
atomicMassUnits → const MassUnit
atto → const MeasurementPrefix
bars → const PressureUnit
baryes → const PressureUnit
candela → const LuminosityUnit
candlepower → const LuminosityUnit
celcius → const TemperatureChangeUnit
celsius → const TemperatureChangeUnit
centi → const MeasurementPrefix
daltons → const MassUnit
days → const TimeUnit
deci → const MeasurementPrefix
degrees → const AngleUnit
deka → const MeasurementPrefix
electronRestMass → const MassUnit
exa → const MeasurementPrefix
fahrenheit → const TemperatureChangeUnit
feet → const DistanceUnit
femto → const MeasurementPrefix
giga → const MeasurementPrefix
gradians → const AngleUnit
grams → const MassUnit
hecto → const MeasurementPrefix
hefnerkerze → const LuminosityUnit
hours → const TimeUnit
inches → const DistanceUnit
inHg → const PressureUnit
kelvin → const TemperatureChangeUnit
kilo → const MeasurementPrefix
longTons → const MassUnit
mega → const MeasurementPrefix
meters → const DistanceUnit
micro → const MeasurementPrefix
miles → const DistanceUnit
milli → const MeasurementPrefix
minutes → const TimeUnit
mmHg → const PressureUnit
moles → const QuantityUnit
nano → const MeasurementPrefix
nauticalMiles → const DistanceUnit
ounces → const MassUnit
pascals → const PressureUnit
peta → const MeasurementPrefix
pico → const MeasurementPrefix
pounds → const MassUnit
psi → const PressureUnit
quecto → const MeasurementPrefix
quetta → const MeasurementPrefix
radians → const AngleUnit
ronna → const MeasurementPrefix
ronto → const MeasurementPrefix
seconds → const TimeUnit
shortTons → const MassUnit
standardAtmospheres → const PressureUnit
technicalAtmospheres → const PressureUnit
tera → const MeasurementPrefix
tonnes → const MassUnit
torr → const PressureUnit
turns → const AngleUnit
units → const QuantityUnit
yards → const DistanceUnit
yocto → const MeasurementPrefix
yotta → const MeasurementPrefix
zepto → const MeasurementPrefix
zetta → const MeasurementPrefix

Properties

cups → VolumeUnit
final
fluidOunces → VolumeUnit
final
gallons → VolumeUnit
final
hertz → FrequencyUnit
final
liters → VolumeUnit
final
pints → VolumeUnit
final
quarts → VolumeUnit
final
tablespoons → VolumeUnit
final
teaspoons → VolumeUnit
final
usCups → VolumeUnit
final
usFluidOunces → VolumeUnit
final
usGallons → VolumeUnit
final
usLegalCups → VolumeUnit
final
usPints → VolumeUnit
final
usQuarts → VolumeUnit
final
usTablespoons → VolumeUnit
final
usTeaspoons → VolumeUnit
final

Functions

cubic<D extends Dimension>(Unit<D> unit, {String? name, MeasurementPrefix prefix = const MeasurementPrefix.unit()}) → DerivedUnit3<UnitNumerator<D>, UnitNumerator<D>, UnitNumerator<D>, D, D, D>
Creates a derived Unit that is the cube of the provided Unit.
infinite<D extends Dimension>(Unit<D> defaultUnit) → Measurement<D>
inverse<D extends Dimension>(Unit<D> unit, {String? name}) → DerivedUnit1<UnitDenominator<D>, D>
Creates a derived Unit that is the inverse of the specified Unit.
nan<D extends Dimension>(Unit<D> defaultUnit) → Measurement<D>
negativeInfinite<D extends Dimension>(Unit<D> defaultUnit) → Measurement<D>
product2<D1 extends Dimension, D2 extends Dimension>(Unit<D1> a, Unit<D2> b, {String? name, MeasurementPrefix? prefix}) → DerivedUnit2<UnitNumerator<D1>, UnitNumerator<D2>, D1, D2>
Creates a derived Unit that is the product of the provided Units.
product3<D1 extends Dimension, D2 extends Dimension, D3 extends Dimension>(Unit<D1> a, Unit<D2> b, Unit<D3> c, {String? name, MeasurementPrefix prefix = const MeasurementPrefix.unit()}) → DerivedUnit3<UnitNumerator<D1>, UnitNumerator<D2>, UnitNumerator<D3>, D1, D2, D3>
Creates a derived Unit that is the product of the provided Units.
ratio<D1 extends Dimension, D2 extends Dimension>(Unit<D1> a, Unit<D2> b, {String? name, MeasurementPrefix? prefix}) → DerivedUnit2<UnitNumerator<D1>, UnitDenominator<D2>, D1, D2>
Creates a derived Unit that is a ratio between the two provided Units.
square<D extends Dimension>(Unit<D> unit, {String? name, MeasurementPrefix? prefix}) → DerivedUnit2<UnitNumerator<D>, UnitNumerator<D>, D, D>
Creates a derived Unit that is the square of the provided Unit.
sum<D extends Dimension>(Iterable<Measurement<D>> parts, {int precision = Precision.maximumPrecision, Unit<D>? defaultUnit}) → Measurement<D>
Creates a measurement that is the sum of several other measurements of the same dimension.
zero<D extends Dimension>(Unit<D> defaultUnit) → Measurement<D>