Advanced Usage

Advanced Usage

The core of this library is a single struct with unit extension methods and standard operators, so there isn't a huge surface of advanced features — but a few things are worth knowing.

Mixing wildly different scales

Because every Distance is stored internally as meters, you can freely combine creation methods from any namespace, no matter how different the scales are:

using MarcusMedina.Units.Distance.Metric;
using MarcusMedina.Units.Distance.Microscopic;

Distance combined = 1.Meters() + 5.Angstroms();
double meters = combined.ToMeters(); // ≈ 1.0000000005

Ratio division

Dividing one Distance by another returns a plain double ratio (not a Distance), useful for "how many times bigger" comparisons:

using MarcusMedina.Units.Distance.Astronomical;
using MarcusMedina.Units.Distance.Metric;

Distance lightYear = 1.LightYears();
Distance km = 1.Kilometers();
double ratio = lightYear / km; // ≈ 9.46e12

Dividing a Distance by a double instead scales it down and still returns a Distance:

Distance half = lightYear / 2.0;

Comparisons across unit families

Distance implements IComparable<Distance> and all six comparison operators, so distances from unrelated unit families compare correctly without manual conversion:

using MarcusMedina.Units.Distance.Astronomical;
using MarcusMedina.Units.Distance.Metric;

bool farther = 1.LightYears() > 100.Kilometers(); // true

Formatting

Distance.ToString() prints the meter value using invariant culture, formatted as "{value} m":

Console.WriteLine(5.Kilometers()); // "5000 m"

There is no built-in support for formatting in a different unit — call the relevant To...() method and format the double yourself.

The Kessel Run easter egg

MarcusMedina.Units.Distance.Astronomical includes ToKesselRun(this Distance d), which always throws an InvalidOperationException explaining that a parsec is a unit of distance, not time — a nod to the famous Star Wars line and a reminder to reach for ToLightYears() instead:

using MarcusMedina.Units.Distance.Astronomical;

12.Parsecs().ToKesselRun();
// throws InvalidOperationException:
// "A parsec (12.00 pc) is a unit of distance, not time. ..."