Getting Started

Getting Started

Install

dotnet add package MarcusMedina.Units.Volume

Requirements: .NET 10.0+, C# 14.0+

How it works

The whole library rests on one idea: Volume always stores its value in millilitres internally, no matter which unit you created it from. Every unit family (metric, US, British, historical Swedish) is just a pair of extension methods:

• a creation extension, e.g. 1.GallonUK(), that turns a number into a Volume
• a conversion extension, e.g. volume.ToLiters(), that reads the Volume back out in a chosen unit

Because the underlying storage is always the same (millilitres), you can freely mix units in the same expression — add a bottle measured in litres to a cask measured in ankare — without ever risking a silent unit-mismatch bug.

That matters especially here: US and UK units that share a name are kept in separate namespaces, because they aren't the same size. A US gallon is ≈ 3.785 L; a UK gallon is ≈ 4.546 L. GallonUS() and GallonUK() are different methods on purpose, so the compiler forces you to be explicit about which one you mean.

Import only the namespace(s) for the unit families you actually use.

First example

using MarcusMedina.Units.Volume.Metric;
using MarcusMedina.Units.Volume.US;

// Create volumes from different unit families
Volume bottle = 750.Milliliters();
Volume jug    = 1.GallonUS();

// Add them together — safe, because both resolve to millilitres internally
Volume totalDrink = bottle + jug;

// Read the total back out in whichever unit is useful
double totalLiters = totalDrink.ToLiters();
double totalCupsUS = totalDrink.ToCupUS();

Console.WriteLine(totalDrink); // ToString() -> "<value> mL"

Arithmetic and comparisons

Volume supports +, -, * (by a scalar double), / (by a scalar, and Volume / Volume for a ratio), plus the full set of comparison operators (<, >, <=, >=, ==, !=) and IComparable<Volume> / IEquatable<Volume>.

using MarcusMedina.Units.Volume.SwedishOld;

Volume cask    = 1.Ankare();
Volume doubled = cask * 2;
bool bigger    = doubled > cask; // true

Next steps

See the API Reference for the full list of supported units, grouped by family.