Struct MassUnit

Encapsulates a mass, stored internally in kilograms (kg), and provides properties that allow for conversions and interactions between multiple metric, imperial, and troy mass units.

Implements

IEquatable<MassUnit>

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Namespace: Scylla.Core.Util.Units

Assembly: ScyllaCore.dll

Syntax

public struct MassUnit : IEquatable<MassUnit>

Remarks

MassUnit uses double precision throughout. The internal representation is kilograms, and all property conversions are routed directly through the kilogram value using fixed constants.

Like LengthUnit, MassUnit supports negative values to allow signed mass differences and offsets. All property setters validate that the assigned value is finite (not NaN or infinite) via NumberUtil.EnsureFinite.

Four groups of units are supported:

• Metric (SI): attogram through kilogram, plus dekagram and hectogram, and metric multiples from metric ton (tonne) through yottaton.
• Imperial / US customary: ounce, pound, stone, short ton (US), long ton (UK).
• Other: carat (gemstone trade), slug (engineering dynamics).
• Troy: troy ounce, troy pound (used for precious metals).

All conversion constants for imperial units use their exact legal definitions (e.g., 1 lb = 0.45359237 kg exactly). The slug constant (14.59390294 kg) is deterministic but not exact by definition.

Equality uses NumberUtil.Approximately; ordering operators use exact kilogram-level comparison.

ToString() automatically selects the most human-readable metric unit (attogram through yottaton). Imperial and troy units are not used in the automatic string representation; access those properties directly if needed.

var m = new MassUnit();
m.Pound = 150;
Console.WriteLine(m.Kilogram);    // ~68.04
Console.WriteLine(m.Stone);       // ~10.71
Console.WriteLine(m);             // "68.04 kg"
var earth = new MassUnit { Kilogram = 5.972e24 };
Console.WriteLine(earth);         // "5.97 Yt"

Constructors

MassUnit(double)

Initializes a new MassUnit instance with the given mass in kilograms.

Declaration

public MassUnit(double kilograms = 0)

Parameters

Type	Name	Description
double	kilograms	The initial mass in kilograms. May be negative (for signed mass differences). Must be finite (not NaN or infinite). Defaults to 0.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if kilograms is NaN or infinite.

Properties

Attogram

Gets or sets the mass expressed in attograms (ag), where 1 ag = 10^-18 g = 10^-21 kg. Attograms are relevant at the scale of individual biomolecules and viruses (a typical virus weighs ~1-100 ag).

Declaration

public double Attogram { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Carat

Gets or sets the mass expressed in metric carats (ct), using the exact definition where 1 ct = 200 mg = 0.0002 kg. The metric carat is the international standard for gemstone and pearl weight (not to be confused with the karat used for gold purity).

Declaration

public double Carat { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Centigram

Gets or sets the mass expressed in centigrams (cg), where 1 cg = 10^-2 g = 10^-5 kg.

Declaration

public double Centigram { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Decigram

Gets or sets the mass expressed in decigrams (dg), where 1 dg = 0.1 g = 10^-4 kg.

Declaration

public double Decigram { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Dekagram

Gets or sets the mass expressed in dekagrams (dag), where 1 dag = 10 g = 0.01 kg.

Declaration

public double Dekagram { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Exaton

Gets or sets the mass expressed in exatons (Et), where 1 Et = 10^18 metric tons = 10^21 kg.

Declaration

public double Exaton { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Femtogram

Gets or sets the mass expressed in femtograms (fg), where 1 fg = 10^-15 g = 10^-18 kg. Femtograms are used in MEMS resonator mass sensing and nano-scale sample measurement.

Declaration

public double Femtogram { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Gigaton

Gets or sets the mass expressed in gigatons (Gt), where 1 Gt = 10^9 metric tons = 10^12 kg. Earth's ocean mass is approximately 1.4 × 10^9 Gt.

Declaration

public double Gigaton { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Gram

Gets or sets the mass expressed in grams (g), where 1 g = 10^-3 kg. The gram is the base unit of mass in the CGS system and a common everyday mass unit.

Declaration

public double Gram { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Hectogram

Gets or sets the mass expressed in hectograms (hg), where 1 hg = 100 g = 0.1 kg.

Declaration

public double Hectogram { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Kilogram

Gets or sets the mass expressed in kilograms (kg), the SI base unit of mass and the canonical internal storage unit of MassUnit. Reading this property returns the raw stored value without conversion.

Declaration

public double Kilogram { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Kiloton

Gets or sets the mass expressed in kilotons (kt), where 1 kt = 1000 metric tons = 10^6 kg. Kilotons are also the standard unit for nuclear weapon yield equivalence (expressed as TNT equivalent).

Declaration

public double Kiloton { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

LongTon

Gets or sets the mass expressed in long tons (UK ton / imperial ton), using the exact definition where 1 long ton = 2240 lb = 1016.0469088 kg. The long ton is used in the UK, particularly in shipping and steel production.

Declaration

public double LongTon { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Megaton

Gets or sets the mass expressed in megatons (Mt), where 1 Mt = 10^6 metric tons = 10^9 kg.

Declaration

public double Megaton { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

MetricTon

Gets or sets the mass expressed in metric tons (also called tonnes, symbol t), where 1 t = 1000 kg. The metric ton is widely used in industry, shipping, and international trade. For the US short ton (2000 lb), see ShortTon; for the UK long ton (2240 lb), see LongTon.

Declaration

public double MetricTon { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Microgram

Gets or sets the mass expressed in micrograms (µg), where 1 µg = 10^-6 g = 10^-9 kg. Micrograms are used in pharmacology (drug dosing) and analytical chemistry.

Declaration

public double Microgram { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Milligram

Gets or sets the mass expressed in milligrams (mg), where 1 mg = 10^-3 g = 10^-6 kg. Common in medication dosing and nutritional labelling.

Declaration

public double Milligram { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Nanogram

Gets or sets the mass expressed in nanograms (ng), where 1 ng = 10^-9 g = 10^-12 kg.

Declaration

public double Nanogram { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Ounce

Gets or sets the mass expressed in avoirdupois ounces (oz), using the exact definition where 1 oz = 1/16 lb = 28.349523125 g. This is the common ounce used for everyday goods in the US and UK. For the precious-metal ounce, use TroyOunce instead.

Declaration

public double Ounce { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Petaton

Gets or sets the mass expressed in petatons (Pt), where 1 Pt = 10^15 metric tons = 10^18 kg. Earth's mass is approximately 5.972 × 10^6 Pt.

Declaration

public double Petaton { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Picogram

Gets or sets the mass expressed in picograms (pg), where 1 pg = 10^-12 g = 10^-15 kg.

Declaration

public double Picogram { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Pound

Gets or sets the mass expressed in avoirdupois pounds (lb), using the exact international definition where 1 lb = 0.45359237 kg. The pound is the primary mass unit in US customary and imperial systems.

Declaration

public double Pound { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

ShortTon

Gets or sets the mass expressed in short tons (US ton), using the exact definition where 1 short ton = 2000 lb = 907.18474 kg. The short ton is the standard ton in the United States. For the metric equivalent, see MetricTon.

Declaration

public double ShortTon { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Slug

Gets or sets the mass expressed in slugs, where 1 slug ≈ 14.59390294 kg. The slug is an imperial engineering unit defined as the mass that accelerates at 1 ft/s² under a force of 1 pound-force. It is primarily used in US aerospace and mechanical engineering. The constant is deterministic but not exact by definition.

Declaration

public double Slug { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Stone

Gets or sets the mass expressed in stones (st), where 1 st = 14 lb = 6.35029318 kg. Stones are used in the UK and Ireland to express human body weight.

Declaration

public double Stone { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Teraton

Gets or sets the mass expressed in teratons (Tt), where 1 Tt = 10^12 metric tons = 10^15 kg.

Declaration

public double Teraton { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

TroyOunce

Gets or sets the mass expressed in troy ounces (oz t), using the exact definition where 1 troy ounce = 31.1034768 g = 0.0311034768 kg. The troy ounce is the internationally accepted standard for precious metals (gold, silver, platinum) and gemstone weight in the jewellery trade. It is heavier than the avoirdupois ounce (Ounce).

Declaration

public double TroyOunce { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

TroyPound

Gets or sets the mass expressed in troy pounds (lb t), where 1 troy pound = 12 troy ounces = 373.2417216 g = 0.3732417216 kg. The troy pound is used in the precious metals trade and is lighter than the avoirdupois pound (Pound).

Declaration

public double TroyPound { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Yottaton

Gets or sets the mass expressed in yottatons (Yt), where 1 Yt = 10^24 metric tons = 10^27 kg. This is the largest metric ton-based unit in MassUnit. The Milky Way galaxy's stellar mass is estimated at roughly 50,000 Yt.

Declaration

public double Yottaton { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Zettaton

Gets or sets the mass expressed in zettatons (Zt), where 1 Zt = 10^21 metric tons = 10^24 kg. The Sun's mass is approximately 1.989 Zt.

Declaration

public double Zettaton { get; set; }

Property Value

Type	Description
double

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown by the setter if the assigned value is NaN or infinite.

Methods

Equals(MassUnit)

Determines whether the specified MassUnit is equal to this instance. Uses NumberUtil.Approximately on the raw kilogram counts to tolerate floating-point rounding from repeated unit conversions.

Declaration

public bool Equals(MassUnit other)

Parameters

Type	Name	Description
MassUnit	other	The MassUnit to compare with this instance.

Returns

Type	Description
bool	true if other has an approximately equal kilogram count; otherwise, false.

Equals(object)

Determines whether the specified object is equal to this MassUnit instance. Only returns true when obj is itself a MassUnit with an approximately equal kilogram count.

Declaration

public override bool Equals(object obj)

Parameters

Type	Name	Description
object	obj	The object to compare with this instance. May be null.

Returns

Type	Description
bool	true if obj is a MassUnit whose kilogram count is approximately equal to this instance; otherwise, false.

Overrides

ValueType.Equals(object)

GetHashCode()

Returns a hash code derived from the raw kilogram count of this instance, suitable for use in hash tables and dictionaries.

Declaration

public override int GetHashCode()

Returns

Type	Description
int	A 32-bit integer hash code based on the internal double kilogram value.

Overrides

ValueType.GetHashCode()

ToString()

Returns a human-readable string that expresses the stored mass in the most appropriate metric unit for the current magnitude.

Declaration

public override string ToString()

Returns

Type

Description

string

A formatted string such as "70 kg", "500 mg", or "1.99 Zt". The sign of negative values is preserved (e.g., "-5 kg"). For zero, returns "0 kg". Selection always uses metric units from attograms (ag) up through yottatons (Yt). Imperial and troy units are never automatically selected - read the corresponding properties (e.g., Pound, TroyOunce) directly for those values. Numeric formatting uses two decimal places for values below 10, one decimal place for values below 100, and zero decimal places otherwise. Trailing zeros and redundant decimal points are trimmed.

Overrides

ValueType.ToString()

Operators

operator +(MassUnit, MassUnit)

Adds two MassUnit values together, combining their kilogram counts.

Declaration

public static MassUnit operator +(MassUnit left, MassUnit right)

Parameters

Type	Name	Description
MassUnit	left	The first operand.
MassUnit	right	The second operand.

Returns

Type	Description
MassUnit	A new MassUnit whose kilogram count equals the sum of left and right.

operator /(MassUnit, MassUnit)

Divides one MassUnit by another, returning the dimensionless ratio of their kilogram counts as a double. Useful for computing scale factors or percentage relationships between masses.

Declaration

public static double operator /(MassUnit left, MassUnit right)

Parameters

Type	Name	Description
MassUnit	left	The dividend.
MassUnit	right	The divisor. Must represent a non-zero kilogram count.

Returns

Type	Description
double	The ratio left.Kilogram / right.Kilogram as a double. The result may be negative if the operands have opposite signs.

Exceptions

Type	Condition
DivideByZeroException	Thrown when right is zero kilograms.

operator /(MassUnit, double)

Divides a MassUnit by a double-precision floating-point scalar, producing a proportionally different mass.

Declaration

public static MassUnit operator /(MassUnit left, double right)

Parameters

Type	Name	Description
MassUnit	left	The MassUnit dividend.
double	right	The scalar divisor. Must be finite and non-zero.

Returns

Type	Description
MassUnit	A new MassUnit whose kilogram count equals left.Kilogram / right.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown when right is NaN or infinite.
DivideByZeroException	Thrown when right is exactly zero.

operator /(MassUnit, int)

Divides a MassUnit by an integer scalar.

Declaration

public static MassUnit operator /(MassUnit left, int right)

Parameters

Type	Name	Description
MassUnit	left	The MassUnit dividend.
int	right	The integer scalar divisor. Must not be zero.

Returns

Type	Description
MassUnit	A new MassUnit whose kilogram count equals left.Kilogram / right.

Exceptions

Type	Condition
DivideByZeroException	Thrown when right is zero.

operator ==(MassUnit, MassUnit)

Determines whether two MassUnit values represent the same mass. Uses NumberUtil.Approximately to tolerate floating-point rounding from unit conversions.

Declaration

public static bool operator ==(MassUnit left, MassUnit right)

Parameters

Type	Name	Description
MassUnit	left	The left operand.
MassUnit	right	The right operand.

Returns

Type	Description
bool	true if the kilogram counts of left and right are approximately equal; otherwise, false.

operator >(MassUnit, MassUnit)

Determines whether one MassUnit is strictly heavier than another. Uses exact kilogram-level comparison (not approximate equality).

Declaration

public static bool operator >(MassUnit left, MassUnit right)

Parameters

Type	Name	Description
MassUnit	left	The left operand.
MassUnit	right	The right operand.

Returns

Type	Description
bool	true if left has more kilograms than right; otherwise, false.

operator >=(MassUnit, MassUnit)

Determines whether one MassUnit is heavier than or equal in mass to another. Uses exact kilogram-level comparison.

Declaration

public static bool operator >=(MassUnit left, MassUnit right)

Parameters

Type	Name	Description
MassUnit	left	The left operand.
MassUnit	right	The right operand.

Returns

Type	Description
bool	true if left has more or the same number of kilograms as right; otherwise, false.

operator !=(MassUnit, MassUnit)

Determines whether two MassUnit values represent different masses. Uses NumberUtil.Approximately for comparison, mirroring the == operator.

Declaration

public static bool operator !=(MassUnit left, MassUnit right)

Parameters

Type	Name	Description
MassUnit	left	The left operand.
MassUnit	right	The right operand.

Returns

Type	Description
bool	true if the kilogram counts of left and right are not approximately equal; otherwise, false.

operator <(MassUnit, MassUnit)

Determines whether one MassUnit is strictly lighter than another. Uses exact kilogram-level comparison (not approximate equality).

Declaration

public static bool operator <(MassUnit left, MassUnit right)

Parameters

Type	Name	Description
MassUnit	left	The left operand.
MassUnit	right	The right operand.

Returns

Type	Description
bool	true if left has fewer kilograms than right; otherwise, false.

operator <=(MassUnit, MassUnit)

Determines whether one MassUnit is lighter than or equal in mass to another. Uses exact kilogram-level comparison.

Declaration

public static bool operator <=(MassUnit left, MassUnit right)

Parameters

Type	Name	Description
MassUnit	left	The left operand.
MassUnit	right	The right operand.

Returns

Type	Description
bool	true if left has fewer or the same number of kilograms as right; otherwise, false.

operator *(MassUnit, double)

Multiplies a MassUnit by a double-precision floating-point scalar, scaling the stored kilogram count proportionally.

Declaration

public static MassUnit operator *(MassUnit left, double right)

Parameters

Type	Name	Description
MassUnit	left	The MassUnit operand.
double	right	The scalar multiplier. Must be finite (not NaN or infinite).

Returns

Type	Description
MassUnit	A new MassUnit whose kilogram count equals left.Kilogram * right.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown when right is NaN or infinite.

operator *(MassUnit, int)

Multiplies a MassUnit by an integer scalar, scaling the stored kilogram count by an exact whole-number factor.

Declaration

public static MassUnit operator *(MassUnit left, int right)

Parameters

Type	Name	Description
MassUnit	left	The MassUnit operand.
int	right	The integer scalar multiplier.

Returns

Type	Description
MassUnit	A new MassUnit whose kilogram count equals left.Kilogram * right.

operator *(double, MassUnit)

Multiplies a double-precision floating-point scalar by a MassUnit, scaling the stored kilogram count proportionally. Allows scalar-first syntax such as 2.5 * someMass.

Declaration

public static MassUnit operator *(double left, MassUnit right)

Parameters

Type	Name	Description
double	left	The scalar multiplier. Must be finite (not NaN or infinite).
MassUnit	right	The MassUnit operand.

Returns

Type	Description
MassUnit	A new MassUnit whose kilogram count equals left * right.Kilogram.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown when left is NaN or infinite.

operator *(int, MassUnit)

Multiplies an integer scalar by a MassUnit, scaling the stored kilogram count by an exact whole-number factor. Allows integer-first syntax such as 3 * someMass.

Declaration

public static MassUnit operator *(int left, MassUnit right)

Parameters

Type	Name	Description
int	left	The integer scalar multiplier.
MassUnit	right	The MassUnit operand.

Returns

Type	Description
MassUnit	A new MassUnit whose kilogram count equals left * right.Kilogram.

operator -(MassUnit, MassUnit)

Subtracts one MassUnit value from another. Because MassUnit supports negative values, the result may be negative.

Declaration

public static MassUnit operator -(MassUnit left, MassUnit right)

Parameters

Type	Name	Description
MassUnit	left	The minuend (the value to subtract from).
MassUnit	right	The subtrahend (the value to subtract).

Returns

Type	Description
MassUnit	A new MassUnit whose kilogram count equals left.Kilogram - right.Kilogram.

operator -(MassUnit)

Negates a MassUnit value, reversing its sign. Useful for expressing a mass deficit or subtractive offset.

Declaration

public static MassUnit operator -(MassUnit value)

Parameters

Type	Name	Description
MassUnit	value	The operand to negate.

Returns

Type	Description
MassUnit	A new MassUnit whose kilogram count equals -value.Kilogram.

Implements

IEquatable<T>