Cookbook

Working with units

You can refer to the core units directly, add a prefix before them, and/or define derived units via per and dot (or square and cubic for area and volume, respectively). Give your materpiece a name if you like:

var myUnit = meters;
var myUnit = milli.meters;
var myUnit = milli.meters.per.second;
var myAreaUnit = meters.by.meters;
var myAreaUnit = square(meters);
var myVolumeUnit = cubic(centi.meters);
var coulombs = seconds.dot.amperes.withName("coulombs");

Creating measurements

You can create a measurement from a unit by "calling" it with the default value you want to give it:

var myMeasurement = myUnit(3.0);

You can also use extensions on num if you know exactly which unit you want:

var myMeasurement = 3.0.centi.meters;

// or, for readability:
var myMeasurement = (3.0).centi.meters;

Build a measurement representing the sum of others, optionally setting the default unit:

var myMeasurement = sum([3.inches, 2.centi.meters, 4.yards]);
var myMeasurement = sum([3.inches, 2.centi.meters, 4.yards], defaultUnit: feet);

You can "call" derived units the same way you would any other unit:

var myVelocity = meters.per.second(3.0);

You can also build a derived measurement from its component parts with over, by, or using:

var myVelocity = 6.meters.over(2.seconds);
var myArea = 3.meters.by(2.feet);
var myVelocity = meters.per.second.using(3.feet, 2.minutes);

Working with measurements

Define a precision either when you create the measurement or any time after:

var myMeasurement = meters(3.1415, precision: 5);
var myMeasurement = (3.1415).meters.withPrecision(5);
var myPreciseMeasurement = myMeasurement.withPrecision(Precision.maximumPrecision);

You can get the raw numerical value a measurement represents in either its default unit or a (valid) unit of your choice:

var myDistanceInMeters = 3.meters.defaultValue;
var myDistanceInFeet = 3.meters.as(feet);

Or, convert a measurement that uses one default unit into a measurement that uses a different default unit (allowing you to continue working with the measurement):

var myDistance = 3.meters.butAs(feet);

The same methods work for derived measurements, except that they accept only the derived units as conversion targets:

var myVelocityInMetersPerSecond = meters.per.second(3.0).defaultValue;
var myVelocityInMilesPerHour = meters.per.second(3.0).as(miles.per.hour);
var myVelocity = meters.per.second(3.0).butAs(miles.per.hour);

Mathematical operators work as you might expect:

var doubleMyDistance = 3.meters * 2.0;
var halfMyDistance = 3.meters / 2.0;
var combinedDistance = 3.meters + 2.feet; // also +=
var differenceInDistance = 3.meters - 2.feet; // also -=
var numberOfTimesItFits = 3.meters ~/ 2.feet;
var remainingDistanceAfterFitting = 3.meters % 2.feet;
var isFarther = 3.meters > 2.feet; // or >=, <, <=, !=, ==

Because measurements can be compared, you can sort lists with them:

[50.feet, 28.inches, 3.meters, 1.miles].sort();
    // [28.inches, 3.meters, 50.feet, 1.miles]