Struct TimeUnit

Encapsulates a duration, stored internally as a double in seconds, and provides properties that allow lossless conversion to and from a comprehensive range of time units -- from Planck time (5.39 x 10^-44 s) up to millennia (10^9 s).

Implements

IEquatable<TimeUnit>

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Namespace: Scylla.Core.Util.Units

Assembly: ScyllaCore.dll

Syntax

public struct TimeUnit : IEquatable<TimeUnit>

Remarks

All property setters validate the incoming value via EnsureFinite(float, string) and will throw ArgumentOutOfRangeException if NaN or infinity is assigned. This makes TimeUnit safe for use in deterministic simulation code where silent propagation of invalid values would be harmful.

Long-duration conversions (year, decade, century, millennium) use the Julian year definition of exactly 365.25 days, giving a fixed, calendar-independent constant of 31,557,600 seconds per year. This ensures deterministic behavior regardless of locale or system calendar.

Equality comparisons (operator ==(TimeUnit, TimeUnit), Equals(TimeUnit)) use Approximately(float, float, float) to account for floating-point rounding. Relational operators (<, >, <=, >=) use exact comparison.

Use ToString() for a human-friendly auto-scaled label, or Formatted(TimeFormat?) with a TimeFormat pattern for precise clock-style or custom formatted output.

// Construct from different units.
var halfHour = new TimeUnit { Minute = 30 };
var sixtySeconds = new TimeUnit(60d);
// Convert freely between units.
double ms = halfHour.Millisecond; // 1,800,000
// Format as a clock string.
string clock = halfHour.Formatted(TimeFormat.StandardClock); // "00:30:00"
// Arithmetic.
TimeUnit total = halfHour + sixtySeconds;
TimeUnit scaled = total * 2d;

Constructors

TimeUnit(double)

Initializes a new TimeUnit with the given duration in seconds.

Declaration

public TimeUnit(double seconds = 0)

Parameters

Type	Name	Description
double	seconds	The duration expressed in seconds. Any finite `double` is accepted, including negative values (which represent durations directed into the past relative to a reference point). Defaults to `0`.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown when `seconds` is NaN or infinity.

Properties

Attosecond

The duration in attoseconds (as), where 1 as = 10^-18 s.

Declaration

public double Attosecond { get; set; }

Property Value

Type	Description
double

Century

Gets or sets the duration expressed in centuries, where 1 century equals 100 Julian years (3,155,760,000 seconds).

Declaration

public double Century { get; set; }

Property Value

Type	Description
double

Day

The duration in days.

Declaration

public double Day { get; set; }

Property Value

Type	Description
double

Decade

Gets or sets the duration expressed in decades, where 1 decade equals 10 Julian years (315,576,000 seconds).

Declaration

public double Decade { get; set; }

Property Value

Type	Description
double

Femtosecond

The duration in femtoseconds (fs), where 1 fs = 10^-15 s.

Declaration

public double Femtosecond { get; set; }

Property Value

Type	Description
double

Fortnight

The duration in fortnights (14 days).

Declaration

public double Fortnight { get; set; }

Property Value

Type	Description
double

Hour

The duration in hours.

Declaration

public double Hour { get; set; }

Property Value

Type	Description
double

Microsecond

The duration in microseconds (µs), where 1 µs = 10^-6 s.

Declaration

public double Microsecond { get; set; }

Property Value

Type	Description
double

Millennium

Gets or sets the duration expressed in millennia, where 1 millennium equals 1,000 Julian years (31,557,600,000 seconds).

Declaration

public double Millennium { get; set; }

Property Value

Type	Description
double

Millisecond

The duration in milliseconds (ms), where 1 ms = 10^-3 s.

Declaration

public double Millisecond { get; set; }

Property Value

Type	Description
double

Minute

The duration in minutes.

Declaration

public double Minute { get; set; }

Property Value

Type	Description
double

Nanosecond

The duration in nanoseconds (ns), where 1 ns = 10^-9 s.

Declaration

public double Nanosecond { get; set; }

Property Value

Type	Description
double

Picosecond

The duration in picoseconds (ps), where 1 ps = 10^-12 s.

Declaration

public double Picosecond { get; set; }

Property Value

Type	Description
double

PlanckTime

Gets or sets the duration expressed in Planck times (t_P), the smallest meaningful unit of time in quantum physics, approximately 5.391247 x 10^-44 seconds.

Declaration

public double PlanckTime { get; set; }

Property Value

Type	Description
double

Remarks

Planck time is provided for completeness in scientific and simulation contexts. At this scale, double precision is the dominant source of error; treat results as approximate. Setting this property validates the incoming value with EnsureFinite(float, string) and throws ArgumentOutOfRangeException if NaN or infinity is supplied.

Second

Gets or sets the duration expressed in seconds. This is the canonical internal representation; reading or writing this property involves no unit conversion.

Declaration

public double Second { get; set; }

Property Value

Type	Description
double

Remarks

All other unit properties delegate their setters through Second. Setting this property validates the incoming value with EnsureFinite(float, string) and throws ArgumentOutOfRangeException if NaN or infinity is supplied.

Week

The duration in weeks.

Declaration

public double Week { get; set; }

Property Value

Type	Description
double

Year

Gets or sets the duration expressed in years, using the Julian year definition of exactly 365.25 days (31,557,600 seconds). This is calendar-independent and safe for deterministic simulation.

Declaration

public double Year { get; set; }

Property Value

Type	Description
double

Yoctosecond

The duration in yoctoseconds (ys), where 1 ys = 10^-24 s.

Declaration

public double Yoctosecond { get; set; }

Property Value

Type	Description
double

Zeptosecond

The duration in zeptoseconds (zs), where 1 zs = 10^-21 s.

Declaration

public double Zeptosecond { get; set; }

Property Value

Type	Description
double

Methods

Equals(TimeUnit)

Determines whether the current TimeUnit instance is equal to another specified TimeUnit instance.

Declaration

public bool Equals(TimeUnit other)

Parameters

Type	Name	Description
TimeUnit	other	The TimeUnit instance to compare to the current instance.

Returns

Type	Description
bool

Equals(object)

Determines whether the specified object is equal to the current TimeUnit instance.

Declaration

public override bool Equals(object obj)

Parameters

Type	Name	Description
object	obj	The object to compare with the current TimeUnit instance.

Returns

Type	Description
bool	True if the specified object is a TimeUnit and has the same value as the current instance; otherwise, false.

Overrides

ValueType.Equals(object)

Formatted(TimeFormat?)

Returns a formatted duration string produced by expanding the token characters in the given TimeFormat pattern against the components of this duration.

Declaration

public string Formatted(TimeFormat? format = null)

Parameters

Type	Name	Description
TimeFormat?	format	The TimeFormat whose Pattern controls which time components are rendered and in what layout. When `null`, or when the pattern is empty, StandardClock (`"HH:mm:ss"`) is used as the fallback.

Returns

Type	Description
string	A string produced by replacing each recognized token run in the pattern with its zero-padded integer (or fractional-second) value, and passing all non-token characters through unchanged. Negative durations are prefixed with a minus sign prepended to the entire output.

Remarks

The decomposition is largest-to-smallest and only allocates each unit when its corresponding token character is present in the pattern. For example, the pattern "mm:ss" expresses the entire duration in minutes and seconds (hours are not extracted, so minutes may exceed 59).

Supported token characters (see IsTokenChar(char)):

Y / YY etc. -- years (Julian, 365.25 days)
W / WW etc. -- weeks
D / DD etc. -- days
H / HH etc. -- hours
m / mm etc. -- minutes
s / ss etc. -- whole seconds
f / ff / fff etc. -- fractional seconds (number of digits = run length)

The run length (number of repeated characters) specifies the minimum field width; values are zero-padded on the left to fill the width. Non-token characters in the pattern are emitted verbatim.

When the s token is absent but f is present, the fractional component is derived from the fractional part of the total absolute seconds (i.e., the whole seconds are not consumed first).

var t = new TimeUnit(3723.456d); // 1 hour, 2 minutes, 3.456 seconds
t.Formatted(new TimeFormat("HH:mm:ss"))       // "01:02:03"
t.Formatted(new TimeFormat("H:mm:ss.fff"))    // "1:02:03.456"
t.Formatted(new TimeFormat("mm:ss"))          // "62:03"  (hours rolled into minutes)
t.Formatted()                                  // "01:02:03" (StandardClock fallback)

GetHashCode()

Computes the hash code for the current TimeUnit instance.

Declaration

public override int GetHashCode()

Returns

Type	Description
int	A 32-bit signed integer hash code representing the current TimeUnit.

Overrides

ValueType.GetHashCode()

ToString()

Returns a human-readable string that represents the duration using the most appropriate unit for the current magnitude, automatically scaling from Planck time up to millennia.

Declaration

public override string ToString()

Returns

Type	Description
string	A string of the form `"{value} {unit}"`, where the unit is chosen as the largest unit whose absolute value is at least 1 when expressed in that unit. For example, 90 seconds returns `"1.5 minutes"`, and 0.001 seconds returns `"1 ms"`. A stored value of exactly `0` returns `"0 seconds"`. Negative values are prefixed with a minus sign (e.g., `"-2 minutes"`).

Overrides

ValueType.ToString()

Remarks

The numeric portion is formatted with adaptive decimal precision: values >= 100 display zero decimals, values >= 10 display one decimal, and smaller values display two decimals. Trailing zeros and trailing decimal separators are trimmed.

For structured output (clock display, countdowns, custom patterns) use Formatted(TimeFormat?) instead.

Operators

operator +(TimeUnit, TimeUnit)

Adds two TimeUnit values together.

Declaration

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

Parameters

Type	Name	Description
TimeUnit	left	The first TimeUnit value.
TimeUnit	right	The second TimeUnit value.

Returns

Type	Description
TimeUnit	A new TimeUnit representing the sum of the two values.

operator /(TimeUnit, TimeUnit)

Divides one TimeUnit value by another, returning the ratio as a double-precision floating-point number.

Declaration

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

Parameters

Type	Name	Description
TimeUnit	left	The TimeUnit value to divide.
TimeUnit	right	The TimeUnit value to divide by.

Returns

Type	Description
double	A double-precision floating-point number representing the ratio of the two values.

Exceptions

Type	Condition
DivideByZeroException	Thrown when `right` is zero.

operator /(TimeUnit, double)

Divides a TimeUnit value by a double-precision floating-point scalar.

Declaration

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

Parameters

Type	Name	Description
TimeUnit	left	The TimeUnit value to divide.
double	right	The double-precision floating-point scalar to divide by.

Returns

Type	Description
TimeUnit	A new TimeUnit representing the quotient of the value and scalar.

Exceptions

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

operator /(TimeUnit, int)

Divides a TimeUnit value by an integer scalar.

Declaration

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

Parameters

Type	Name	Description
TimeUnit	left	The TimeUnit value to divide.
int	right	The integer scalar to divide by.

Returns

Type	Description
TimeUnit	A new TimeUnit representing the quotient of the value and scalar.

Exceptions

Type	Condition
DivideByZeroException	Thrown when `right` is zero.

operator ==(TimeUnit, TimeUnit)

Determines whether two TimeUnit values are approximately equal.

Declaration

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

Parameters

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

Returns

Type	Description
bool	True if the two values are approximately equal; otherwise, false.

operator >(TimeUnit, TimeUnit)

Determines whether one TimeUnit value is greater than another.

Declaration

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

Parameters

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

Returns

Type	Description
bool	True if `left` is greater than `right`; otherwise, false.

operator >=(TimeUnit, TimeUnit)

Determines whether one TimeUnit value is greater than or equal to another.

Declaration

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

Parameters

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

Returns

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

operator !=(TimeUnit, TimeUnit)

Determines whether two TimeUnit values are not approximately equal.

Declaration

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

Parameters

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

Returns

Type	Description
bool	True if the two values are not approximately equal; otherwise, false.

operator <(TimeUnit, TimeUnit)

Determines whether one TimeUnit value is less than another.

Declaration

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

Parameters

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

Returns

Type	Description
bool	True if `left` is less than `right`; otherwise, false.

operator <=(TimeUnit, TimeUnit)

Determines whether one TimeUnit value is less than or equal to another.

Declaration

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

Parameters

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

Returns

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

operator *(TimeUnit, double)

Multiplies a TimeUnit value by a double-precision floating-point scalar.

Declaration

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

Parameters

Type	Name	Description
TimeUnit	left	The TimeUnit value to multiply.
double	right	The double-precision floating-point scalar to multiply by.

Returns

Type	Description
TimeUnit	A new TimeUnit representing the product of the value and scalar.

Exceptions

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

operator *(TimeUnit, int)

Multiplies a TimeUnit value by an integer scalar.

Declaration

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

Parameters

Type	Name	Description
TimeUnit	left	The TimeUnit value to multiply.
int	right	The integer scalar to multiply by.

Returns

Type	Description
TimeUnit	A new TimeUnit representing the product of the value and scalar.

operator *(double, TimeUnit)

Multiplies a double-precision floating-point scalar by a TimeUnit value.

Declaration

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

Parameters

Type	Name	Description
double	left	The double-precision floating-point scalar to multiply.
TimeUnit	right	The TimeUnit value to multiply by.

Returns

Type	Description
TimeUnit	A new TimeUnit representing the product of the scalar and value.

Exceptions

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

operator *(int, TimeUnit)

Multiplies an integer scalar by a TimeUnit value.

Declaration

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

Parameters

Type	Name	Description
int	left	The integer scalar to multiply.
TimeUnit	right	The TimeUnit value to multiply by.

Returns

Type	Description
TimeUnit	A new TimeUnit representing the product of the scalar and value.

operator -(TimeUnit, TimeUnit)

Subtracts one TimeUnit value from another.

Declaration

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

Parameters

Type	Name	Description
TimeUnit	left	The TimeUnit value to subtract from.
TimeUnit	right	The TimeUnit value to subtract.

Returns

Type	Description
TimeUnit	A new TimeUnit representing the difference of the two values.

operator -(TimeUnit)

Negates a TimeUnit value.

Declaration

public static TimeUnit operator -(TimeUnit value)

Parameters

Type	Name	Description
TimeUnit	value	The TimeUnit value to negate.

Returns

Type	Description
TimeUnit	A new TimeUnit representing the negated value.

Implements

IEquatable<T>