Release v. 2.2.0. Support for default interpreters for measurements, used in toString() methods.

Author: mongoose13

CHANGELOG.md

@@ -2,6 +2,12 @@
 Dependency-free, type-safe Dart unit conversion library. Decouple specific unit
 types you need to work with from the rest of your code.
 
+## [2.2.0] - 2023-02-16
+### Added
+- toString() methods on interpreters produce the standard short form of the unit
+- toString() methods on measurements use the interpreter that created the measurement
+- Support for metric prefixes "quecto", "ronto", "ronna", "quetta"
+
 ## [2.1.1] - 2023-01-17
 ### Fixed
 - Prevent precision cap breach when performing additions
@@ -172,6 +178,7 @@ types you need to work with from the rest of your code.
 ### Added
 - Initial package setup
 
+[2.2.0]: https://bitbucket.org/mongoose13/fling-units/commits/tag/2.2.0/
 [2.1.1]: https://bitbucket.org/mongoose13/fling-units/commits/tag/2.1.1/
 [2.1.0]: https://bitbucket.org/mongoose13/fling-units/commits/tag/2.1.0/
 [2.0.2]: https://bitbucket.org/mongoose13/fling-units/commits/tag/2.0.2/

example/lib/example.dart

@@ -99,7 +99,7 @@ void main() {
   print('${fuelConsumption.as(kilo.meters, usGallons)} kpg');
 
   var coulombs = seconds(4).by(amperes(8));
-  print('My invention generates $coulombs coulombs!');
+  print('My invention generates $coulombs!');
 
   //------------------------------------------------//
 
@@ -110,5 +110,27 @@ void main() {
   print(
       '\nMy bucket is ${myBucketSize.compareMagnitude(yourBucketSize)} times bigger than yours!');
 
+  //------------------------------------------------//
+
+  // The unit interpreters themselves have a toString() method that will produce
+  // the "standard" short form of the unit. Measurements will make use of that
+  // in their own toString() methods using whichever unit was used to
+  // instantiate them. You can also change the default unit later.
+  final goldAmount = 1234.milli.grams.withPrecision(Precision(4));
+  print('I have $goldAmount of gold!');
+  print('I have ${goldAmount.as(kilo.grams)} ${kilo.grams} of gold!');
+  print('I have ${goldAmount.withDefaultUnit(ounces)} of gold!');
+
+  // This is also true for derived units. The library will produce a default
+  // unit name, but you can also supply your own.
+  final carSpeed = DerivedMeasurement<Distance, Time>.divide(
+    100.miles.withPrecision(Precision(3)),
+    1.hours.withPrecision(Precision(3)),
+  );
+  print('\nMy car is going $carSpeed!');
+  final carVelocity = carSpeed.withDefaultUnit(DerivedMeasurementInterpreter(
+      feet, minutes, true, MeasurementPrefix.unit(), 'gizmos per doodad'));
+  print('My car is going $carVelocity!');
+
   // Have fun!
 }

lib/src/core/interpreter.dart

@@ -14,21 +14,36 @@ part of fling_units;
 /// [Measurement] instances for interpretation (typically via an `as()` method,
 /// such as [Area.as]).
 abstract class MeasurementInterpreter<T> {
+  /// The prefix to apply to the measurement.
+  final MeasurementPrefix _prefix;
+
   /// Interprets the base value according to the configured unit.
-  double _of(final num value) => value.toDouble() * _unitMultiplier;
+  double _of(final num value) =>
+      value.toDouble() * _unitMultiplier / _prefix._multiplier;
 
   /// Interprets the provided value as if it were of the configured unit,
   /// returning the base value.
-  double _from(final num value) => value.toDouble() / _unitMultiplier;
+  double _from(final num value) =>
+      value.toDouble() / _unitMultiplier * _prefix._multiplier;
+
+  /// The standardized short form name of the unit (e.g. "m" for meters).
+  final String _name;
 
   /// Creates a measurement based on the value and the configured multiplier.
   T call(final double value, {final Precision precision = Precision.max});
 
   /// Constructs a [MeasurementInterpreter].
-  const MeasurementInterpreter._(this._unitMultiplier);
+  const MeasurementInterpreter._(
+    this._name,
+    this._unitMultiplier,
+    this._prefix,
+  );
 
   /// The multiplier for the configured unit.
   final double _unitMultiplier;
+
+  @override
+  String toString() => '$_prefix$_name';
 }
 
 /// A [MeasurementInterpreter] that rounds its results to `int`s.
@@ -39,12 +54,17 @@ abstract class RoundingMeasurementInterpreter<T>
     extends MeasurementInterpreter<T> {
   @override
   double _of(final num value) =>
-      (value.toDouble() * _unitMultiplier).roundToDouble();
+      (value.toDouble() * _unitMultiplier / _prefix._multiplier)
+          .roundToDouble();
 
   @override
-  double _from(final num value) => value.toDouble() / _unitMultiplier;
+  double _from(final num value) =>
+      value.toDouble() / _unitMultiplier * _prefix._multiplier;
 
   /// Constructs a [RoundingMeasurementInterpreter].
-  const RoundingMeasurementInterpreter._(final double unitMultiplier)
-      : super._(unitMultiplier);
+  const RoundingMeasurementInterpreter._(
+    final String name,
+    final double unitMultiplier, [
+    final MeasurementPrefix prefix = const MeasurementPrefix.unit(),
+  ]) : super._(name, unitMultiplier, prefix);
 }

lib/src/core/precision.dart

@@ -104,7 +104,7 @@ class Precision {
   }
 
   /// Interprets the specified number according to this Precision.
-  double withPrecision(final double value) =>
+  double withPrecision(final num value) =>
       double.parse(value.toStringAsPrecision(precision));
 
   @override

lib/src/core/prefix.dart

@@ -12,69 +12,192 @@ class MeasurementPrefix
         TimePrefix,
         VolumePrefix {
   /// Constructs an arbitrary [MeasurementPrefix].
-  const MeasurementPrefix(this._multiplier);
+  const MeasurementPrefix(
+    this._multiplier, {
+    final String name = '',
+  }) : _name = name;
+
+  /// The default prefix (equivalent to no prefix).
+  const MeasurementPrefix.unit()
+      : _multiplier = 1.0,
+        _name = '';
 
-  /// The configured multiplier.
-  @override
   final double _multiplier;
+
+  /// The standardized short form name of the prefix (e.g. "m" for milli).
+  final String _name;
+
+  @override
+  MeasurementPrefix get _prefix => this;
+
+  @override
+  String toString() => _name;
+
+  /// SI prefix "quecto".
+  static final MeasurementPrefix _quecto =
+      const MeasurementPrefix(1e-30, name: 'q');
+
+  /// SI prefix "ronto".
+  static final MeasurementPrefix _ronto =
+      const MeasurementPrefix(1e-27, name: 'r');
+
+  /// SI prefix "yocto".
+  static final MeasurementPrefix _yocto =
+      const MeasurementPrefix(1e-24, name: 'y');
+
+  /// SI prefix "zepto".
+  static final MeasurementPrefix _zepto =
+      const MeasurementPrefix(1e-21, name: 'z');
+
+  /// SI prefix "atto".
+  static final MeasurementPrefix _atto =
+      const MeasurementPrefix(1e-18, name: 'a');
+
+  /// SI prefix "femto".
+  static final MeasurementPrefix _femto =
+      const MeasurementPrefix(1e-15, name: 'f');
+
+  /// SI prefix "pico".
+  static final MeasurementPrefix _pico =
+      const MeasurementPrefix(1e-12, name: 'p');
+
+  /// SI prefix "nano".
+  static final MeasurementPrefix _nano =
+      const MeasurementPrefix(1e-9, name: 'n');
+
+  /// SI prefix "micro".
+  static final MeasurementPrefix _micro =
+      const MeasurementPrefix(1e-6, name: 'μ');
+
+  /// SI prefix "milli".
+  static final MeasurementPrefix _milli =
+      const MeasurementPrefix(1e-3, name: 'm');
+
+  /// SI prefix "centi".
+  static final MeasurementPrefix _centi =
+      const MeasurementPrefix(1e-2, name: 'c');
+
+  /// SI prefix "deci".
+  static final MeasurementPrefix _deci =
+      const MeasurementPrefix(1e-1, name: 'd');
+
+  /// SI prefix "deka".
+  static final MeasurementPrefix _deka =
+      const MeasurementPrefix(1e1, name: 'da');
+
+  /// SI prefix "hecto".
+  static final MeasurementPrefix _hecto =
+      const MeasurementPrefix(1e2, name: 'h');
+
+  /// SI prefix "kilo".
+  static final MeasurementPrefix _kilo =
+      const MeasurementPrefix(1e3, name: 'k');
+
+  /// SI prefix "mega".
+  static final MeasurementPrefix _mega =
+      const MeasurementPrefix(1e6, name: 'M');
+
+  /// SI prefix "giga".
+  static final MeasurementPrefix _giga =
+      const MeasurementPrefix(1e9, name: 'G');
+
+  /// SI prefix "tera".
+  static final MeasurementPrefix _tera =
+      const MeasurementPrefix(1e12, name: 'T');
+
+  /// SI prefix "peta".
+  static final MeasurementPrefix _peta =
+      const MeasurementPrefix(1e15, name: 'P');
+
+  /// SI prefix "exa".
+  static final MeasurementPrefix _exa =
+      const MeasurementPrefix(1e18, name: 'E');
+
+  /// SI prefix "zetta".
+  static final MeasurementPrefix _zetta =
+      const MeasurementPrefix(1e21, name: 'Z');
+
+  /// SI prefix "yotta".
+  static final MeasurementPrefix _yotta =
+      const MeasurementPrefix(1e24, name: 'Y');
+
+  /// SI prefix "ronna".
+  static final MeasurementPrefix _ronna =
+      const MeasurementPrefix(1e27, name: 'R');
+
+  /// SI prefix "quetta".
+  static final MeasurementPrefix _quetta =
+      const MeasurementPrefix(1e30, name: 'Q');
 }
 
+/// SI prefix "quecto".
+final MeasurementPrefix quecto = MeasurementPrefix._quecto;
+
+/// SI prefix "ronto".
+final MeasurementPrefix ronto = MeasurementPrefix._ronto;
+
 /// SI prefix "yocto".
-final MeasurementPrefix yocto = MeasurementPrefix(1e-24);
+final MeasurementPrefix yocto = MeasurementPrefix._yocto;
 
 /// SI prefix "zepto".
-final MeasurementPrefix zepto = MeasurementPrefix(1e-21);
+final MeasurementPrefix zepto = MeasurementPrefix._zepto;
 
 /// SI prefix "atto".
-final MeasurementPrefix atto = MeasurementPrefix(1e-18);
+final MeasurementPrefix atto = MeasurementPrefix._atto;
 
 /// SI prefix "femto".
-final MeasurementPrefix femto = MeasurementPrefix(1e-15);
+final MeasurementPrefix femto = MeasurementPrefix._femto;
 
 /// SI prefix "pico".
-final MeasurementPrefix pico = MeasurementPrefix(1e-12);
+final MeasurementPrefix pico = MeasurementPrefix._pico;
 
 /// SI prefix "nano".
-final MeasurementPrefix nano = MeasurementPrefix(1e-9);
+final MeasurementPrefix nano = MeasurementPrefix._nano;
 
 /// SI prefix "micro".
-final MeasurementPrefix micro = MeasurementPrefix(1e-6);
+final MeasurementPrefix micro = MeasurementPrefix._micro;
 
 /// SI prefix "milli".
-final MeasurementPrefix milli = MeasurementPrefix(1e-3);
+final MeasurementPrefix milli = MeasurementPrefix._milli;
 
 /// SI prefix "centi".
-final MeasurementPrefix centi = MeasurementPrefix(1e-2);
+final MeasurementPrefix centi = MeasurementPrefix._centi;
 
 /// SI prefix "deci".
-final MeasurementPrefix deci = MeasurementPrefix(1e-1);
+final MeasurementPrefix deci = MeasurementPrefix._deci;
 
 /// SI prefix "deka".
-final MeasurementPrefix deka = MeasurementPrefix(1e1);
+final MeasurementPrefix deka = MeasurementPrefix._deka;
 
 /// SI prefix "hecto".
-final MeasurementPrefix hecto = MeasurementPrefix(1e2);
+final MeasurementPrefix hecto = MeasurementPrefix._hecto;
 
 /// SI prefix "kilo".
-final MeasurementPrefix kilo = MeasurementPrefix(1e3);
+final MeasurementPrefix kilo = MeasurementPrefix._kilo;
 
 /// SI prefix "mega".
-final MeasurementPrefix mega = MeasurementPrefix(1e6);
+final MeasurementPrefix mega = MeasurementPrefix._mega;
 
 /// SI prefix "giga".
-final MeasurementPrefix giga = MeasurementPrefix(1e9);
+final MeasurementPrefix giga = MeasurementPrefix._giga;
 
 /// SI prefix "tera".
-final MeasurementPrefix tera = MeasurementPrefix(1e12);
+final MeasurementPrefix tera = MeasurementPrefix._tera;
 
 /// SI prefix "peta".
-final MeasurementPrefix peta = MeasurementPrefix(1e15);
+final MeasurementPrefix peta = MeasurementPrefix._peta;
 
 /// SI prefix "exa".
-final MeasurementPrefix exa = MeasurementPrefix(1e18);
+final MeasurementPrefix exa = MeasurementPrefix._exa;
 
 /// SI prefix "zetta".
-final MeasurementPrefix zetta = MeasurementPrefix(1e21);
+final MeasurementPrefix zetta = MeasurementPrefix._zetta;
 
 /// SI prefix "yotta".
-final MeasurementPrefix yotta = MeasurementPrefix(1e24);
+final MeasurementPrefix yotta = MeasurementPrefix._yotta;
+
+/// SI prefix "ronna".
+final MeasurementPrefix ronna = MeasurementPrefix._ronna;
+
+/// SI prefix "quetta".
+final MeasurementPrefix quetta = MeasurementPrefix._quetta;