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: Precision(2)).kilometers; // 4.8, not 4.82803...

Classes

Angle: Represents an angle.
AngleInterpreter
Area: Represents the two-dimensional derived unit of perpendicular distances.
AreaInterpreter: Interprets Areas as a specific unit.
Charge: Measures electric charge.
ChargeInterpreter: Interprets Charges as a specific unit.
DerivedMeasurement<A extends Measurement<A>, B extends Measurement<B>>: A measurement representing two simpler measurements tied together by either multiplication or division.
DerivedMeasurementInterpreter<A extends Measurement<A>, B extends Measurement<B>>: An interpreter for derived measurements (from two basic measurements).
Distance: Represents a single dimension of distance.
DistanceInterpreter: Interprets Distances as a specific unit.
Luminosity: Measures luminous intensity.
LuminosityInterpreter: Interprets Luminositys as a specific unit.
Mass: Represents an amount of mass.
MassInterpreter: Interprets Masses as a specific unit.
Measurement<T extends Measurement<T>>: Base class for any type of measurement.
MeasurementInterpreter<T>: Interprets a measurement as a specific unit.
MeasurementPrefix: Multiplies a Measurement by a prefix.
MeasurementVisitor: Base class for measurement visitors.
NumExtender: Wrapper class for extensions on num types.
Precision: Represents the amount of precision for a measurement.
Pressure
PressureInterpreter
Quantity: Measures a number of discrete items.
QuantityInterpreter: Base class for Quantity interpreters.
RoundingMeasurementInterpreter<T>: A MeasurementInterpreter that rounds its results to ints.
RoundingQuantityInterpreter: Interprets Quantitys as a specific unit, truncating results.
StandardQuantityInterpreter: Interprets Quantitys as a specific unit.
Temperature: Represents a "thermometer" temperature.
TemperatureChange: Represents a change in temperature.
TemperatureChangeInterpreter: The MeasurementInterpreter for TemperatureChanges.
Time: Represents a duration of time.
TimeInterpreter: Interprets Time as a specific unit.
Volume: Represents a three-dimensional space.
VolumeInterpreter: Interprets Volumes as specific units.

Mixins

AnglePrefix
ChargePrefix: Applies a prefix to various quantity units.
DistancePrefix: Applies a prefix to various distance units.
LuminosityPrefix: Applies a prefix to various quantity units.
MassPrefix
PressurePrefix
QuantityPrefix: Applies a prefix to various quantity units.
TemperaturePrefix: Applies a prefix to various time units.
TimePrefix: Applies a prefix to various time units.
VolumePrefix: Applies a prefix to various volume units.

Extensions

NumExtension: Measurement constructor extension for the num types.

Constants

amperes → const ChargeInterpreter: The interpreter for amperes.
arcMinutes → const AngleInterpreter: The interpreter for arc minutes.
arcSeconds → const AngleInterpreter: The interpreter for arc seconds.
atomicMassUnits → const MassInterpreter: The interpreter for atomic mass units.
bars → const PressureInterpreter: The interpreter for bars of pressure.
baryes → const PressureInterpreter: The interpreter for Baryes.
candela → const LuminosityInterpreter: The interpreter for candela.
candlepower → const LuminosityInterpreter: The interpreter for candlepower.
celcius → const TemperatureChangeInterpreter: The interpreter for degrees Celcius.
cups → const VolumeInterpreter: The interpreter for cups.
daltons → const MassInterpreter: The interpreter for daltons.
days → const TimeInterpreter: The interpreter for days.
degrees → const AngleInterpreter: The interpreter for degrees.
electronRestMass → const MassInterpreter: The interpreter for electron rest mass.
fahrenheit → const TemperatureChangeInterpreter: The interpreter for degrees Fahrenheit.
feet → const DistanceInterpreter: The interpreter for feet.
fluidOunces → const VolumeInterpreter: The interpreter for fluid ounces.
gallons → const VolumeInterpreter: The interpreter for gallons.
gradians → const AngleInterpreter: The interpreter for gradians.
grams → const MassInterpreter: The interpreter for grams.
hefnerkerze → const LuminosityInterpreter: The interpreter for Hefnerkerze.
hours → const TimeInterpreter: The interpreter for hours.
inches → const DistanceInterpreter: The interpreter for inches.
inHg → const PressureInterpreter: The interpreter for inches of mercury.
kelvin → const TemperatureChangeInterpreter: The interpreter for Kelvin.
liters → const VolumeInterpreter: The interpreter for liters.
longTons → const MassInterpreter: The interpreter for long tons.
meters → const DistanceInterpreter: The interpreter for meters.
miles → const DistanceInterpreter: The interpreter for miles.
minutes → const TimeInterpreter: The interpreter for minutes.
mmHg → const PressureInterpreter: The interpreter for millimeters of mercury.
moles → const StandardQuantityInterpreter: The interpreter for moles.
nauticalMiles → const DistanceInterpreter: The interpreter for nautical miles.
ounces → const MassInterpreter: The interpreter for ounces.
pascals → const PressureInterpreter: The interpreter for Pascals.
pints → const VolumeInterpreter: The interpreter for pints.
pounds → const MassInterpreter: The interpreter for pounds.
psi → const PressureInterpreter: The interpreter for pound-force per square inch.
quarts → const VolumeInterpreter: The interpreter for quarts.
radians → const AngleInterpreter: The interpreter for radians.
seconds → const TimeInterpreter: The interpreter for seconds.
shortTons → const MassInterpreter: The interpreter for short tons.
standardAtmospheres → const PressureInterpreter: The interpreter for standard atmospheres of pressure.
tablespoons → const VolumeInterpreter: The interpreter for tablespoons.
teaspoons → const VolumeInterpreter: The interpreter for teaspoons.
technicalAtmospheres → const PressureInterpreter: The interpreter for technical atmospheres of pressure.
tonnes → const MassInterpreter: The interpreter for tonnes.
torr → const PressureInterpreter: The interpreter for Torr.
turns → const AngleInterpreter: The interpreter for turns.
units → const RoundingQuantityInterpreter: The interpreter for units.
usCups → const VolumeInterpreter: The interpreter for US cups.
usFluidOunces → const VolumeInterpreter: The interpreter for US fluid ounces.
usGallons → const VolumeInterpreter: The interpreter for US gallons.
usLegalCups → const VolumeInterpreter: The interpreter for US legal cups.
usPints → const VolumeInterpreter: The interpreter for US pints.
usQuarts → const VolumeInterpreter: The interpreter for US quarts.
usTablespoons → const VolumeInterpreter: The interpreter for US tablespoons.
usTeaspoons → const VolumeInterpreter: The interpreter for US teaspoons.
yards → const DistanceInterpreter: The interpreter for yards.

Properties

atto → MeasurementPrefix: SI prefix "atto".
final
centi → MeasurementPrefix: SI prefix "centi".
final
deci → MeasurementPrefix: SI prefix "deci".
final
deka → MeasurementPrefix: SI prefix "deka".
final
exa → MeasurementPrefix: SI prefix "exa".
final
femto → MeasurementPrefix: SI prefix "femto".
final
giga → MeasurementPrefix: SI prefix "giga".
final
hecto → MeasurementPrefix: SI prefix "hecto".
final
kilo → MeasurementPrefix: SI prefix "kilo".
final
mega → MeasurementPrefix: SI prefix "mega".
final
micro → MeasurementPrefix: SI prefix "micro".
final
milli → MeasurementPrefix: SI prefix "milli".
final
nano → MeasurementPrefix: SI prefix "nano".
final
peta → MeasurementPrefix: SI prefix "peta".
final
pico → MeasurementPrefix: SI prefix "pico".
final
quecto → MeasurementPrefix: SI prefix "quecto".
final
quetta → MeasurementPrefix: SI prefix "quetta".
final
ronna → MeasurementPrefix: SI prefix "ronna".
final
ronto → MeasurementPrefix: SI prefix "ronto".
final
tera → MeasurementPrefix: SI prefix "tera".
final
yocto → MeasurementPrefix: SI prefix "yocto".
final
yotta → MeasurementPrefix: SI prefix "yotta".
final
zepto → MeasurementPrefix: SI prefix "zepto".
final
zetta → MeasurementPrefix: SI prefix "zetta".
final

fling_units library

Classes

Mixins

Extensions

Constants

Properties

fling_units package

fling_units library