me_sure_meant 2.0.0

Visionary Software Solutions Measurement API ==> Making Measurements, Units, and Physical Quantities in your applications a dream come true!

example/me_sure_meant_example.dart

import 'dart:math';

import 'package:me_sure_meant/me_sure_meant.dart';

/// It may seem like this package is useless now!
/// All the demos and cool implemented functionality are in modules built on top
/// lenny, energizr, massive, temper, god_of_the_mind, and pump_up_the_volume
/// but there are cool building blocks here that people can use to make their
/// own modules. For purely demonstrative purposes, we'll implement a couple
/// of cute examples that may someday live in their own extension modules.

/// Space: The Final Frontier.
final class AstronomicalUnit implements Length {
  const AstronomicalUnit();
  @override
  String get symbol => "au";
  @override
  String toString() => symbol;
}

/// These are the voyages of the Starship Enterprise...
final class AstronomicalUnits extends PhysicalQuantities<Length> {
  const AstronomicalUnits(final Measurement m) : super(m, const AstronomicalUnit());
  /// This is where one would convert to a common base unit
  /// like metre in lenny. This conversion enables +/-,
  /// it is a FACTORY METHOD called with the result of a calculation to maintain
  /// immutability. In this example, AU will act as its own fundamental unit
  @override
  PhysicalQuantities<Length> baseUnit(final Measurement q) =>  AstronomicalUnits(q);

  /// This yields the basis for compareTo and comparison operators as well as
  /// the value used in +/-. For instance, one might convert imperial tons
  /// to kilograms as a fundamental unit.
  @override
  Measurement fundamental() => magnitude;

  /// This enables the user-friendly experience of fluency between units.
  /// A real implementation would probably convert to Metres and other units
  /// of [Length]. Here we'll just play with our examples.
  @override
  PhysicalQuantity<Length> toUnit(final Length u) => switch(u) {
      AstronomicalUnit() => this,
      LightYear() => LightYears.from(this),
      _ => throw UnimplementedError("Don't bring any Death Stars this way!")
    };

  /// In a real design, this might live in a mixin or some dynamically loaded STRATEGY.
  /// for simplicity, we'll just have these two know about each other intimately.
  factory AstronomicalUnits.from(final LightYears buzz) => AstronomicalUnits(buzz.magnitude.multiplied(63241));
}

/// Are you Buzzed about this [Unit]?
final class LightYear implements Length {
  const LightYear();
  @override
  String get symbol => "ly";
  @override
  String toString() => symbol;
}

/// Since there's no Woody here, this one will just use AUs as a fundamental.
/// The conversion is known as:
///  astronomical units	   63241 au
/// https://en.wikipedia.org/wiki/Light-year
final class LightYears extends PhysicalQuantities<Length> {
  const LightYears(final Measurement m) : super(m, const LightYear());

  @override
  PhysicalQuantities<Length> baseUnit(final Measurement q)  => AstronomicalUnits(q);

  @override
  Measurement fundamental() => toUnit(AstronomicalUnit()).magnitude;

  @override
  PhysicalQuantity<Length> toUnit(Length u)  => switch(u) {
    LightYear() => this,
    AstronomicalUnit() => AstronomicalUnits.from(this),
    _ => throw UnimplementedError("No X-Wings either!")
  };
  factory LightYears.from(final AstronomicalUnits au) => LightYears(au.magnitude.divided(63241));
}

/// Now let's see them in action!
void main() {
  ///  Going 1 light year is something that would be nice to see in our lifetime!
  var oneSmallStepForMan = LightYears(crude(1));
  var wowThatIsFar = oneSmallStepForMan.toUnit(AstronomicalUnit());
  print(wowThatIsFar);
  assert(wowThatIsFar.magnitude.toNum() == 63241 && wowThatIsFar.unit is AstronomicalUnit);
  var wannaBeEnder = oneSmallStepForMan + LightYears(crude(10));
  print(wannaBeEnder);
  print(wannaBeEnder.toUnit(AstronomicalUnit()));
  /// Uncertainty is supported out of the box! Let's say val is 4 +- 2 AU away.
  /// and yes I know I'm going from Star Trek to the Enderverse while avoiding
  /// dubious Star Wars memes. Engage!
  var valentineCatchingUp = AstronomicalUnits(uncertain(402561, 213745));
  print(valentineCatchingUp);
  /// do you know what this is in lightyears? well, now we do!
  print(valentineCatchingUp.toUnit(LightYear()));
  /// Wow, Jane took her Outside.... where did she end up?
  var introducingJane = Random();
  var outside = AstronomicalUnits(uncertain(introducingJane.nextInt(123456789), introducingJane.nextInt(987654321)));
  var somewhere = valentineCatchingUp + outside;
  print("See how the uncertainties added? $somewhere");
  assert(
  (somewhere.magnitude as BasicUncertainty).uncertainty ==
      (valentineCatchingUp.magnitude as BasicUncertainty).uncertainty + (outside.magnitude as BasicUncertainty).uncertainty);
  print("Now go have your own fun adventures implementing units!");
}