Advanced Usage

Advanced Usage

Most of what there is to know about MarcusMedina.Units.Volume lives on the API Reference page. This page covers the parts that go beyond simple creation and conversion.

US vs. UK units are kept apart on purpose

The library never lets a "gallon" or "pint" be ambiguous. MarcusMedina.Units.Volume.US and MarcusMedina.Units.Volume.British define separate methods for units that share an English name but not a size:

using MarcusMedina.Units.Volume.US;
using MarcusMedina.Units.Volume.British;

Volume us = 1.GallonUS(); // 3 785.412 mL
Volume uk = 1.GallonUK(); // 4 546.09 mL

There's no plain Gallon() method — you always have to say which one you mean. That's a deliberate API design choice, not an oversight: a silent mix-up here is a ~20% error, which is exactly the kind of mistake a type system should make impossible rather than just hard.

Mixing families freely

Because every unit ultimately creates a Volume backed by millilitres, values from different namespaces combine directly:

using MarcusMedina.Units.Volume.Metric;
using MarcusMedina.Units.Volume.SwedishOld;

Volume total = 1.5.Liters() + 1.Ankare(); // bottle + beer cask, safely summed

Arithmetic and ratios

Volume supports +, -, and scaling by a double via * / /. Dividing two Volume values (rather than a Volume by a double) returns a plain double ratio:

Volume doubled = 1.Kanna() * 2;
double ratio   = 1.Ankare() / 1.Kanna(); // 15.0 — an ankare is 15 kannor

Comparisons and sorting

Volume implements IComparable<Volume> and IEquatable<Volume> plus the full set of comparison operators, so a List<Volume> sorts correctly out of the box:

var volumes = new List<Volume> { 1.GallonUS(), 1.GallonUK(), 1.Kanna() };
volumes.Sort();

ToString formatting

Volume.ToString() always renders the underlying millilitre value in invariant culture, e.g. "1000 mL", regardless of which unit the value was created from.

Historical Swedish units

MarcusMedina.Units.Volume.SwedishOld models pre-1889 Swedish volume units with Kanna (2.6177 L) as the practical reference point — Jungfru (1/4 stop), Stop (1/8 kanna), Ankare (15 kannor, a beer cask size), and Tunna (48 kannor, a dry-goods barrel for grain). These are useful for historical text conversion or just as a curiosity — they follow the same creation/conversion pattern as every other unit family.