Migration Guide for v2.x to v3.x

Static Methods

Measurement classes have been renamed with "Measurement" at the end of the name. For example, "Distance" became "DistanceMeasurement". In version 3, "Distance" is a dimension rather than a measurement.

If you refer to the old measurement class name, switch to using the more general Measurement<D>.

For example:

// v2
<Distance>[3.inches, 2.feet]

// v3
<Measurement<Distance>>[3.inches, 2.feet]

If you use any of the constructors for a measurement, switch to the new name or use the Measurement equivalent. If you don't need const-ness, you can use the global method. This also applies to infinite, negativeInfinite, zero, nan, and sum.

For example:

// v2
Distance.infinite()

// v3
DistanceMeasurement.infinite()
// or
Measurement.infinite(meters)
// or
infinite(meters)
// you can also specify the dimension type for type safety
infinite<Distance>(meters);

Area

The Area series of classes has been completely removed. Instead, area units and measurements are built using two distances, or a distance squared.

square

The square method has been made global.

If you used the square method, you no longer need to refer to it as a static method on Area.

For example:

// v2
Area.square(inches)

// v3
square(inches)

Static Methods

If you use any of the static methods on Area, replace them with a square distance derived unit.

For example:

// v2
Area.zero()

// v3
Measurement.zero(square(meters))
// or
zero(square(meters))

of

Instantiating area measurements by passing in component parts is replaced by the using method on the derived unit.

If you use of, instead use using on the default area unit.

For example:

// v2
Area.of(2.meters, 3.feet)

// v3
square(meters).using(2.meters, 3.feet)

as and asArea

The as method became the only way to convert any unit. For an area measurement, aspreviously accepted two inputs, but in v3 accepts only one (the way asArea did).

If you use as on an area measurement, instead create or provide the derived unit you intend to convert to.

For example:

// v2
Area.square(inches)(3).as(meters, meters)

// v3
3.square(inches).as(square(meters))
// or
3.square(inches).as(product2(meters, meters))

If you use asArea, replace it with as only.

For example:

// v2
Area.square(inches)(3).asArea(Area.square(meters))

// v3
3.square(inches).as(square(meters))

Volume

The Volume series of classes has been completely removed. Instead, volume units and measurements are built using three distances, or a distance cubed. The "native" units are unchanged (e.g. liters).

cubic

The cubic method has been made global.

If you used the cubic method, you no longer need to refer to it as a static method on Volume.

For example:

// v2
Volume.cubic(feet)

// v3
cubic(feet)

Static Methods

If you used any of the static methods on Volume, replace them with a cubic distance derived unit.

For example:

// v2
Volume.zero()

// v3
Measurement.zero(cubic(meters))
// or
zero(cubic(meters))

of

Instantiating volume measurements by passing in component parts is replaced by the using method on the derived unit.

If you use of, instead use using on the default volume unit.

For example:

// v2
Volume.of(2.meters, 3.feet, 4.inches)

// v3
cubic(meters).using(2.meters, 3.feet, 4.inches)

as and asVolume

The as method became the only way to convert any unit. For a volume measurement, aspreviously accepted three inputs, but in v3 accepts only one (the way asVolume did).

If you use as on a volume measurement, instead create or provide the derived unit you intend to convert to.

For example:

// v2
3.liters.as(meters, meters, meters)

// v3
3.liters.as(cubic(meters))
// or
3.liters.as(product3(meters, meters, meters))

If you use asVolume, replace it with as only.

For example:

// v2
3.liters.asVolume(cups)

// v3
3.liters.as(cups)

by and per

Creating derived units and measurements is done through the derived unit itself. The by and per methods on measurements have been replaced by methods that build the derived units more easily.

If you use by or per, switch to instantiating the derived unit and "calling" it to create the measurement.

For example:

// v2
24.miles.per(2.gallons)

// v3
ratio(miles, gallons)(24, 2)
// or
ratio(miles, gallons)(12)

DerivedMeasurement

The DerivedMeasurement class has been removed. Its features can be replicated by instantiating derived units.

If you use DerivedMeasurement.divide or DerivedMeasurement.multiply, switch to instantiating the derived unit and "calling" it.

For example:

// v2
DerivedMeasurement<Distance, Time>.divide(100.miles, 2.hours)

// v3
ratio(miles, hours)(100, 2)
// or
ratio(miles, hours)(50)

DerivedMeasurementInterpreter

The DerivedMeasurementInterpreter class has been removed. Derived units are created via the global methods or the appropriate DerivedUnitX constructor.

If you use DerivedMeasurementInterpreter, switch to instantiating units via the global methods.

For example:

// v2
DerivedMeasurementInterpreter(
    feet,
    minutes,
    true,
    MeasurementPrefix.unit(),
    "feet per minute",
  )

// v3
ratio(feet, minute, "feet per minute")
// or
DerivedUnit2.from(UnitNumerator(feet), UnitDenominator(minutes), name: "feet per minute")

Default Units

The withDefaultUnit method has been renamed butAs.

If you use withDefaultUnit, replace it with butAs.

For example:

// v2
3.meters.withDefaultUnit(feet)

// v3
3.meters.butAs(feet)