Meziantou.FrameworkFrameDuration Struct
An exact, non-negative frame display duration expressed as a normalized rational number of seconds.
public readonly struct FrameDuration : IComparable, IComparable<FrameDuration>, IEquatable<FrameDuration>Remarks
Durations are stored exactly so that GIF (hundredths of a second) and APNG (delay_num / delay_den) timing survives import without rounding. The value is normalized: the numerator and the denominator have no common divisor, the denominator is positive, and zero is always represented as 0/1. Two durations are equal when they represent the same rational value.
default(FrameDuration) is a valid zero duration. Zero durations are preserved as-is; the library never applies the minimum-delay heuristics used by some players.
Constructors
| Name | Description |
|---|---|
| FrameDuration(long, long) | Initializes a new instance of the FrameDuration struct from a rational number of seconds. |
FrameDuration(long, long)
FrameDuration.csInitializes a new instance of the FrameDuration struct from a rational number of seconds.
Parameters
numeratorlong- The numerator, in seconds. Must be zero or positive.
denominatorlong- The denominator. Must be positive.
Exceptions
ArgumentOutOfRangeExceptionnumeratoris negative ordenominatoris not positive.
Properties
| Name | Description |
|---|---|
| Denominator | Gets the normalized denominator. Always positive. |
| IsZero | Gets a value indicating whether the duration is zero. |
| Numerator | Gets the normalized numerator, in seconds. |
| TotalMilliseconds | Gets the duration in milliseconds, as a floating-point approximation. |
| TotalSeconds | Gets the duration in seconds, as a floating-point approximation. |
| Zero | Gets a zero duration. |
Denominator
FrameDuration.csIsZero
FrameDuration.csNumerator
FrameDuration.csTotalMilliseconds
FrameDuration.csTotalSeconds
FrameDuration.csZero
FrameDuration.csMethods
| Name | Description |
|---|---|
| Add(FrameDuration) | Returns the exact sum of this duration and another one, like this + other. |
| CompareTo(FrameDuration) | Compares the current instance with another object of the same type and returns an integer that indicates whether the current instance precedes, follows, or occurs in the same position in the sort order as the other object. |
| CompareTo(object?) | Compares the current instance with another object of the same type and returns an integer that indicates whether the current instance precedes, follows, or occurs in the same position in the sort order as the other object. |
| Equals(FrameDuration) | Indicates whether the current object is equal to another object of the same type. |
| Equals(object?) | Indicates whether this instance and a specified object are equal. |
| FromMilliseconds(long) | Creates a duration from a whole number of milliseconds. |
| FromTimeSpan(TimeSpan) | Creates a duration from a TimeSpan. The conversion is exact (ticks are 100 ns). |
| GetHashCode() | Returns the hash code for this instance. |
| Subtract(FrameDuration) | Returns the exact difference of this duration and another one, like this - other. |
| ToString() | Returns the duration formatted as {Numerator}/{Denominator} s. |
| ToTimeSpan() | Converts the duration to a TimeSpan, rounding to the nearest tick (ties round up). |
Add(FrameDuration)
FrameDuration.csReturns the exact sum of this duration and another one, like this + other.
public FrameDuration Add(FrameDuration other)Parameters
otherFrameDuration- The duration to add.
Returns
FrameDuration The normalized sum.
Exceptions
OverflowException- The normalized numerator or denominator of the sum is greater than
Int64.MaxValue.
Remarks
The sum is computed exactly with 128-bit integers and then normalized. It is never rounded: a sum whose normalized numerator or denominator does not fit in a Int64 throws instead (for example two durations whose denominators are large coprime numbers).
CompareTo overloads
CompareTo(FrameDuration)
FrameDuration.csCompares the current instance with another object of the same type and returns an integer that indicates whether the current instance precedes, follows, or occurs in the same position in the sort order as the other object.
public int CompareTo(FrameDuration other)Parameters
otherFrameDuration- An object to compare with this instance.
Returns
int A value that indicates the relative order of the objects being compared. The return value has these meanings:
| Value | Meaning |
|---|---|
| Less than zero | This instance precedes other in the sort order. |
| Zero | This instance occurs in the same position in the sort order as other. |
| Greater than zero | This instance follows other in the sort order. |
CompareTo(object?)
FrameDuration.csCompares the current instance with another object of the same type and returns an integer that indicates whether the current instance precedes, follows, or occurs in the same position in the sort order as the other object.
Parameters
objobject?- An object to compare with this instance.
Returns
int A value that indicates the relative order of the objects being compared. The return value has these meanings:
| Value | Meaning |
|---|---|
| Less than zero | This instance precedes obj in the sort order. |
| Zero | This instance occurs in the same position in the sort order as obj. |
| Greater than zero | This instance follows obj in the sort order. |
Exceptions
ArgumentExceptionobjis not the same type as this instance.
Equals overloads
Equals(FrameDuration)
FrameDuration.csIndicates whether the current object is equal to another object of the same type.
public bool Equals(FrameDuration other)Parameters
otherFrameDuration- An object to compare with this object.
Returns
bool true if the current object is equal to the other parameter; otherwise, false.
Equals(object?)
FrameDuration.csFromMilliseconds(long)
FrameDuration.csCreates a duration from a whole number of milliseconds.
public static FrameDuration FromMilliseconds(long milliseconds)Parameters
millisecondslong- The number of milliseconds. Must be zero or positive.
Returns
FrameDuration The exact duration milliseconds / 1000 seconds.
Exceptions
ArgumentOutOfRangeExceptionmillisecondsis negative.
FromTimeSpan(TimeSpan)
FrameDuration.csCreates a duration from a TimeSpan. The conversion is exact (ticks are 100 ns).
public static FrameDuration FromTimeSpan(TimeSpan value)Parameters
valueTimeSpan- The time span. Must be zero or positive.
Returns
FrameDuration The exact duration ticks / 10,000,000 seconds.
Exceptions
ArgumentOutOfRangeExceptionvalueis negative.
GetHashCode()
FrameDuration.csSubtract(FrameDuration)
FrameDuration.csReturns the exact difference of this duration and another one, like this - other.
public FrameDuration Subtract(FrameDuration other)Parameters
otherFrameDuration- The duration to subtract. It must not be longer than this duration.
Returns
FrameDuration The normalized difference.
Exceptions
OverflowExceptionotheris longer than this duration, or the normalized denominator of the difference is greater thanInt64.MaxValue.
Remarks
The difference is computed exactly, like FrameDuration.Add. A duration is never negative, so a difference below zero throws instead of being clamped to FrameDuration.Zero.
ToString()
FrameDuration.csToTimeSpan()
FrameDuration.csConverts the duration to a TimeSpan, rounding to the nearest tick (ties round up).
public TimeSpan ToTimeSpan()Returns
TimeSpan The time span.
Exceptions
OverflowException- The duration is greater than
TimeSpan.MaxValue.
Remarks
The conversion is exact when the duration is a whole number of 100 ns ticks (for example any duration created by FrameDuration.FromTimeSpan or FrameDuration.FromMilliseconds, and GIF hundredths). Otherwise the result is the nearest tick, rounding exact halves up; the computation uses 128-bit integers and never loses precision before rounding. Durations that round above TimeSpan.MaxValue throw instead of being clamped.
Operators
| Name | Description |
|---|---|
| operator +(FrameDuration, FrameDuration) | Adds two durations exactly (see FrameDuration.Add). |
| operator ==(FrameDuration, FrameDuration) | Compares two durations for equality. |
| operator >(FrameDuration, FrameDuration) | Determines whether a duration is longer than another. |
| operator >=(FrameDuration, FrameDuration) | Determines whether a duration is longer than or equal to another. |
| operator !=(FrameDuration, FrameDuration) | Compares two durations for inequality. |
| operator <(FrameDuration, FrameDuration) | Determines whether a duration is shorter than another. |
| operator <=(FrameDuration, FrameDuration) | Determines whether a duration is shorter than or equal to another. |
| operator -(FrameDuration, FrameDuration) | Subtracts a duration from another exactly (see FrameDuration.Subtract). |
operator +(FrameDuration, FrameDuration)
FrameDuration.csAdds two durations exactly (see FrameDuration.Add).
public static FrameDuration operator +(FrameDuration left, FrameDuration right)Parameters
leftFrameDuration- The first duration.
rightFrameDuration- The second duration.
Returns
FrameDuration The normalized sum.
Exceptions
OverflowException- The normalized numerator or denominator of the sum is greater than
Int64.MaxValue.
operator ==(FrameDuration, FrameDuration)
FrameDuration.csCompares two durations for equality.
public static bool operator ==(FrameDuration left, FrameDuration right)Parameters
leftFrameDuration- The first duration.
rightFrameDuration- The second duration.
Returns
bool true if both represent the same rational value; otherwise false.
operator >(FrameDuration, FrameDuration)
FrameDuration.csDetermines whether a duration is longer than another.
public static bool operator >(FrameDuration left, FrameDuration right)Parameters
leftFrameDuration- The first duration.
rightFrameDuration- The second duration.
Returns
bool true if left is longer than right.
operator >=(FrameDuration, FrameDuration)
FrameDuration.csDetermines whether a duration is longer than or equal to another.
public static bool operator >=(FrameDuration left, FrameDuration right)Parameters
leftFrameDuration- The first duration.
rightFrameDuration- The second duration.
Returns
bool true if left is longer than or equal to right.
operator !=(FrameDuration, FrameDuration)
FrameDuration.csCompares two durations for inequality.
public static bool operator !=(FrameDuration left, FrameDuration right)Parameters
leftFrameDuration- The first duration.
rightFrameDuration- The second duration.
Returns
bool true if the durations differ; otherwise false.
operator <(FrameDuration, FrameDuration)
FrameDuration.csDetermines whether a duration is shorter than another.
public static bool operator <(FrameDuration left, FrameDuration right)Parameters
leftFrameDuration- The first duration.
rightFrameDuration- The second duration.
Returns
bool true if left is shorter than right.
operator <=(FrameDuration, FrameDuration)
FrameDuration.csDetermines whether a duration is shorter than or equal to another.
public static bool operator <=(FrameDuration left, FrameDuration right)Parameters
leftFrameDuration- The first duration.
rightFrameDuration- The second duration.
Returns
bool true if left is shorter than or equal to right.
operator -(FrameDuration, FrameDuration)
FrameDuration.csSubtracts a duration from another exactly (see FrameDuration.Subtract).
public static FrameDuration operator -(FrameDuration left, FrameDuration right)Parameters
leftFrameDuration- The duration to subtract from.
rightFrameDuration- The duration to subtract. It must not be longer than
left.
Returns
FrameDuration The normalized difference.
Exceptions
OverflowExceptionrightis longer thanleft, or the normalized denominator of the difference is greater thanInt64.MaxValue.