Struct AreaUnit

Encapsulates an area, stored internally in square meters (m²), and provides properties that allow for conversions and interactions between multiple metric, imperial, land, nautical, and astronomical area units.

Implements

IEquatable<AreaUnit>

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Namespace: Scylla.Core.Util.Units

Assembly: ScyllaCore.dll

Syntax

public struct AreaUnit : IEquatable<AreaUnit>

Remarks

The canonical internal representation is square meters (m²) stored as a double. All property getters and setters convert to and from this value using compile-time constant factors derived from exact SI or IAU definitions. Assigning any non-finite value (NaN or infinity) to any property or constructor parameter throws an ArgumentOutOfRangeException via NumberUtil.EnsureFinite.

Imperial area conversions use exact SI definitions: 1 inch = 0.0254 m (exact), which propagates to all foot, yard, mile, rod, acre, rood, section, and township conversions. The acre is defined as exactly 43,560 ft². The nautical mile is exactly 1,852 m.

Astronomical conversions use deterministic constants: 1 AU = 149,597,870,700 m (exact), 1 light-year uses a Julian year of exactly 365.25 days and the exact speed of light (299,792,458 m/s), and parsec-based units use the IAU value of approximately 3.0856775814913673e16 m per parsec.

Equality comparisons (==, !=, Equals(AreaUnit)) use approximate floating-point equality via NumberUtil.Approximately rather than exact bit-for-bit comparison, avoiding false inequality from accumulated floating-point rounding during unit conversions.

ToString() automatically selects the most human-readable unit for the stored value, spanning from square femtometers (fm²) at atomic scales up through square gigaparsecs (Gpc²) at cosmological scales.

Constructors

AreaUnit(double)

Creates a new AreaUnit instance from a square meter (m²) value.

Declaration

public AreaUnit(double squareMeters = 0)

Parameters

Type	Name	Description
double	squareMeters	The area in square meters (m²). Must be a finite value; NaN and infinity are rejected with an ArgumentOutOfRangeException. Defaults to 0.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown when squareMeters is NaN or infinite.

Properties

Acre

The area in acres, where 1 acre = 43,560 ft² (exact).

Declaration

public double Acre { get; set; }

Property Value

Type	Description
double

Are

The area in ares (a), where 1 a = 100 m².

Declaration

public double Are { get; set; }

Property Value

Type	Description
double

Decare

The area in decares (daa), where 1 daa = 1000 m².

Declaration

public double Decare { get; set; }

Property Value

Type	Description
double

Hectare

The area in hectares (ha), where 1 ha = 10,000 m².

Declaration

public double Hectare { get; set; }

Property Value

Type	Description
double

Rood

The area in roods, where 1 rood = 1/4 acre.

Declaration

public double Rood { get; set; }

Property Value

Type	Description
double

Section

The area in sections (US PLSS), where 1 section = 1 square mile (mi²).

Declaration

public double Section { get; set; }

Property Value

Type	Description
double

SquareAstronomicalUnit

The area in square astronomical units (AU²), where 1 AU = 149,597,870,700 m (exact).

Declaration

public double SquareAstronomicalUnit { get; set; }

Property Value

Type	Description
double

SquareCable

The area in square cables, where 1 cable = 0.1 nautical miles = 185.2 m (exact).

Declaration

public double SquareCable { get; set; }

Property Value

Type	Description
double

SquareCentimeter

The area in square centimeters (cm²).

Declaration

public double SquareCentimeter { get; set; }

Property Value

Type	Description
double

SquareDecimeter

The area in square decimeters (dm²), where 1 dm = 0.1 m.

Declaration

public double SquareDecimeter { get; set; }

Property Value

Type	Description
double

SquareFemtometer

The area in square femtometers (fm²), where 1 fm = 10^-15 m.

Declaration

public double SquareFemtometer { get; set; }

Property Value

Type	Description
double

SquareFoot

The area in square feet (ft²), where 1 ft = 0.3048 m (exact).

Declaration

public double SquareFoot { get; set; }

Property Value

Type	Description
double

SquareGigaparsec

The area in square gigaparsecs (Gpc²), where 1 Gpc = 10^9 pc ≈ 3.086e25 m. Appropriate for cosmological-scale areas spanning the observable universe.

Declaration

public double SquareGigaparsec { get; set; }

Property Value

Type	Description
double

SquareInch

The area in square inches (in²), where 1 in = 0.0254 m (exact).

Declaration

public double SquareInch { get; set; }

Property Value

Type	Description
double

SquareKilometer

The area in square kilometers (km²), where 1 km² = 1,000,000 m².

Declaration

public double SquareKilometer { get; set; }

Property Value

Type	Description
double

SquareKiloparsec

The area in square kiloparsecs (kpc²), where 1 kpc = 1,000 pc ≈ 3.086e19 m. Appropriate for galactic-scale areas.

Declaration

public double SquareKiloparsec { get; set; }

Property Value

Type	Description
double

SquareLightYear

The area in square light-years (ly²), using a deterministic Julian year (365.25 days).

Declaration

public double SquareLightYear { get; set; }

Property Value

Type	Description
double

SquareMegaparsec

The area in square megaparsecs (Mpc²), where 1 Mpc = 10^6 pc ≈ 3.086e22 m. Appropriate for galaxy-cluster and large-scale structure areas.

Declaration

public double SquareMegaparsec { get; set; }

Property Value

Type	Description
double

SquareMeter

The area in square meters (m²). This is the canonical internal unit; getting and setting this property directly avoids any conversion arithmetic.

Declaration

public double SquareMeter { get; set; }

Property Value

Type	Description
double

SquareMicrometer

The area in square micrometers (µm²), where 1 µm = 10^-6 m.

Declaration

public double SquareMicrometer { get; set; }

Property Value

Type	Description
double

SquareMile

The area in square miles (mi²), where 1 mi = 1609.344 m (exact).

Declaration

public double SquareMile { get; set; }

Property Value

Type	Description
double

SquareMillimeter

The area in square millimeters (mm²).

Declaration

public double SquareMillimeter { get; set; }

Property Value

Type	Description
double

SquareNanometer

The area in square nanometers (nm²), where 1 nm = 10^-9 m.

Declaration

public double SquareNanometer { get; set; }

Property Value

Type	Description
double

SquareNauticalMile

The area in square nautical miles (nmi²), where 1 nmi = 1852 m (exact).

Declaration

public double SquareNauticalMile { get; set; }

Property Value

Type	Description
double

SquareParsec

The area in square parsecs (pc²), where 1 pc ≈ 3.0856775814913673e16 m (IAU definition). Appropriate for stellar neighborhoods and nearby galaxies.

Declaration

public double SquareParsec { get; set; }

Property Value

Type	Description
double

SquarePicometer

The area in square picometers (pm²), where 1 pm = 10^-12 m.

Declaration

public double SquarePicometer { get; set; }

Property Value

Type	Description
double

SquareRod

The area in square rods (rod²) (square perch / square pole), where 1 rod = 16.5 feet.

Declaration

public double SquareRod { get; set; }

Property Value

Type	Description
double

SquareYard

The area in square yards (yd²), where 1 yd = 0.9144 m (exact).

Declaration

public double SquareYard { get; set; }

Property Value

Type	Description
double

Township

The area in townships (US PLSS), where 1 township = 36 sections = 36 square miles (mi²).

Declaration

public double Township { get; set; }

Property Value

Type	Description
double

Methods

Equals(AreaUnit)

Determines whether the specified AreaUnit is approximately equal to this instance by comparing internal square-meter values via NumberUtil.Approximately. This tolerates small rounding errors that can accumulate during unit conversions.

Declaration

public bool Equals(AreaUnit other)

Parameters

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

Returns

Type	Description
bool	true if other is approximately equal to this instance; otherwise false.

Equals(object)

Determines whether the specified object is equal to this AreaUnit instance. Uses approximate floating-point equality via Equals(AreaUnit).

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 an AreaUnit and is approximately equal to this instance; otherwise false.

Overrides

ValueType.Equals(object)

GetHashCode()

Returns a hash code for this instance based on the raw internal square-meter value.

Declaration

public override int GetHashCode()

Returns

Type	Description
int	An integer hash code derived from the stored double square-meter value. Note that two values considered approximately equal by Equals(AreaUnit) may produce different hash codes if their raw bit representations differ.

Overrides

ValueType.GetHashCode()

ToString()

Returns a human-readable string representation of this area using the most appropriate unit selected automatically based on the magnitude of the stored value.

Declaration

public override string ToString()

Returns

Type

Description

string

A string containing a rounded numeric value followed by a unit abbreviation, such as "100 m²", "2.5 ha", or "1.5 AU²". Returns "0 m²" when the stored value is exactly zero. The unit selection steps from largest to smallest, preferring astronomical scales first, then land and metric scales, then sub-meter SI prefix scales: Cosmological: Gpc², Mpc², kpc², pc², ly², AU². Large metric and land: km², ha, acre, daa, a. Human metric: m², dm², cm², mm². Sub-millimeter SI: µm², nm², pm², fm². Imperial units (ft², yd², mi², etc.) are not used for automatic display selection. Use the corresponding properties directly to format in a specific imperial unit. Decimal places are automatically reduced for larger numbers: 2 decimals below 10, 1 decimal from 10 to 99, and 0 decimals at 100 or above. Trailing zeros and trailing decimal separators are trimmed.

Overrides

ValueType.ToString()

Operators

operator +(AreaUnit, AreaUnit)

Adds two AreaUnit values together by summing their internal square-meter representations.

Declaration

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

Parameters

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

Returns

Type	Description
AreaUnit	A new AreaUnit whose value equals left plus right.

operator /(AreaUnit, AreaUnit)

Divides one AreaUnit value by another, returning the dimensionless ratio of their magnitudes as a double-precision floating-point number.

Declaration

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

Parameters

Type	Name	Description
AreaUnit	left	The dividend area.
AreaUnit	right	The divisor area. Must be non-zero.

Returns

Type	Description
double	The ratio of left to right as a double, representing how many times larger left is than right.

Exceptions

Type	Condition
DivideByZeroException	Thrown when right is zero.

operator /(AreaUnit, double)

Divides an AreaUnit value by a double-precision floating-point scalar, reducing the area by the given divisor.

Declaration

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

Parameters

Type	Name	Description
AreaUnit	left	The area to divide.
double	right	The divisor. Must be a finite, non-zero value; NaN and infinity are rejected, and zero causes a DivideByZeroException.

Returns

Type	Description
AreaUnit	A new AreaUnit equal to left divided by right.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown when right is not finite (NaN or infinity).
DivideByZeroException	Thrown when right is zero.

operator /(AreaUnit, int)

Divides an AreaUnit value by an integer scalar, reducing the area by the given divisor.

Declaration

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

Parameters

Type	Name	Description
AreaUnit	left	The area to divide.
int	right	The integer divisor. Must be non-zero.

Returns

Type	Description
AreaUnit	A new AreaUnit equal to left divided by right.

Exceptions

Type	Condition
DivideByZeroException	Thrown when right is zero.

operator ==(AreaUnit, AreaUnit)

Determines whether two AreaUnit values are approximately equal by comparing their internal square-meter values using NumberUtil.Approximately, which tolerates small floating-point rounding errors from unit conversions.

Declaration

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

Parameters

Type	Name	Description
AreaUnit	left	The first value to compare.
AreaUnit	right	The second value to compare.

Returns

Type	Description
bool	true if left and right are approximately equal; otherwise false.

operator >(AreaUnit, AreaUnit)

Determines whether one AreaUnit value is strictly greater than another, comparing their internal square-meter representations.

Declaration

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

Parameters

Type	Name	Description
AreaUnit	left	The first value to compare.
AreaUnit	right	The second value to compare.

Returns

Type	Description
bool	true if left is strictly greater than right; otherwise false.

operator >=(AreaUnit, AreaUnit)

Determines whether one AreaUnit value is greater than or equal to another, comparing their internal square-meter representations.

Declaration

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

Parameters

Type	Name	Description
AreaUnit	left	The first value to compare.
AreaUnit	right	The second value to compare.

Returns

Type	Description
bool	true if left is greater than or equal to right; otherwise false.

operator !=(AreaUnit, AreaUnit)

Determines whether two AreaUnit values are not approximately equal by comparing their internal square-meter values using NumberUtil.Approximately.

Declaration

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

Parameters

Type	Name	Description
AreaUnit	left	The first value to compare.
AreaUnit	right	The second value to compare.

Returns

Type	Description
bool	true if left and right are not approximately equal; otherwise false.

operator <(AreaUnit, AreaUnit)

Determines whether one AreaUnit value is strictly less than another, comparing their internal square-meter representations.

Declaration

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

Parameters

Type	Name	Description
AreaUnit	left	The first value to compare.
AreaUnit	right	The second value to compare.

Returns

Type	Description
bool	true if left is strictly less than right; otherwise false.

operator <=(AreaUnit, AreaUnit)

Determines whether one AreaUnit value is less than or equal to another, comparing their internal square-meter representations.

Declaration

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

Parameters

Type	Name	Description
AreaUnit	left	The first value to compare.
AreaUnit	right	The second value to compare.

Returns

Type	Description
bool	true if left is less than or equal to right; otherwise false.

operator *(AreaUnit, double)

Multiplies an AreaUnit value by a double-precision floating-point scalar, scaling the area by the given factor.

Declaration

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

Parameters

Type	Name	Description
AreaUnit	left	The area to scale.
double	right	The scalar multiplier. Must be a finite value; NaN and infinity are rejected.

Returns

Type	Description
AreaUnit	A new AreaUnit equal to left scaled by right.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown when right is not finite (NaN or infinity).

operator *(AreaUnit, int)

Multiplies an AreaUnit value by an integer scalar, scaling the area by the given factor.

Declaration

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

Parameters

Type	Name	Description
AreaUnit	left	The area to scale.
int	right	The integer scalar multiplier.

Returns

Type	Description
AreaUnit	A new AreaUnit equal to left scaled by right.

operator *(double, AreaUnit)

Multiplies a double-precision floating-point scalar by an AreaUnit value, scaling the area by the given factor.

Declaration

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

Parameters

Type	Name	Description
double	left	The scalar multiplier. Must be a finite value; NaN and infinity are rejected.
AreaUnit	right	The area to scale.

Returns

Type	Description
AreaUnit	A new AreaUnit equal to right scaled by left.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown when left is not finite (NaN or infinity).

operator *(int, AreaUnit)

Multiplies an integer scalar by an AreaUnit value, scaling the area by the given factor.

Declaration

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

Parameters

Type	Name	Description
int	left	The integer scalar multiplier.
AreaUnit	right	The area to scale.

Returns

Type	Description
AreaUnit	A new AreaUnit equal to right scaled by left.

operator -(AreaUnit, AreaUnit)

Subtracts one AreaUnit value from another by subtracting their internal square-meter representations.

Declaration

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

Parameters

Type	Name	Description
AreaUnit	left	The minuend.
AreaUnit	right	The subtrahend.

Returns

Type	Description
AreaUnit	A new AreaUnit whose value equals left minus right.

operator -(AreaUnit)

Negates an AreaUnit value, producing an area whose internal square-meter value is the arithmetic negation of the original.

Declaration

public static AreaUnit operator -(AreaUnit value)

Parameters

Type	Name	Description
AreaUnit	value	The value to negate.

Returns

Type	Description
AreaUnit	A new AreaUnit whose internal m² value is the arithmetic negation of value.

Implements

IEquatable<T>