Struct Instant64

Represents an instant on the global timeline, with nanosecond resolution. This type is a equivalent to Instant, but with a more limited range (a few hundred years either side of the Unix epoch) and more compact, high performance representation. It is expected to be used in conjunction with Duration64, typically in scenarios where performance and/or memory usage are important. Note that in most cases, Instant is more appropriate and convenient (with more supported methods etc). This should effectively be regarded as a specialist type for unusually performance-sensitive scenarios.
Since 3.3.x
Availability net8.0, netstandard2.0
Implements
Inherited Members
Namespace: NodaTime.HighPerformance
Assembly: NodaTime.dll
Syntax
public readonly struct Instant64 : IEquatable<Instant64>, IComparable<Instant64>, IFormattable, IComparable, IAdditionOperators<Instant64, Duration64, Instant64>, ISubtractionOperators<Instant64, Duration64, Instant64>, ISubtractionOperators<Instant64, Instant64, Duration64>, IComparisonOperators<Instant64, Instant64, bool>, IEqualityOperators<Instant64, Instant64, bool>, IMinMaxValue<Instant64>
Remarks

An Instant64 has no concept of a particular time zone or calendar: it simply represents a point in time that can be globally agreed-upon.

Equality and ordering comparisons are defined in the natural way, with earlier points on the timeline being considered "less than" later points.

The default value of this type is UnixEpoch, i.e. the instant which can be represented as 1970-01-01T00:00:00Z in the ISO calendar.

Properties

MaxValue

Represents the largest possible Instant64.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static Instant64 MaxValue { get; }
Property Value
Type Description
Instant64
Remarks
This value is equivalent to 2262-04-11T23:47:16.854775807Z.

MinValue

Represents the smallest possible Instant64.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static Instant64 MinValue { get; }
Property Value
Type Description
Instant64
Remarks
This value is equivalent to 1677-09-21T00:12:43.145224192Z.

UnixEpoch

The instant at the Unix epoch of midnight 1st January 1970 UTC.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static Instant64 UnixEpoch { get; }
Property Value
Type Description
Instant64

Methods

Add(Instant64, Duration64)

Adds a duration to an instant. Friendly alternative to operator+().
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static Instant64 Add(Instant64 left, Duration64 right)
Parameters
Type Name Description
Instant64 left The left hand side of the operator.
Duration64 right The right hand side of the operator.
Returns
Type Description
Instant64 A new Instant64 representing the sum of the given values.

CompareTo(Instant64)

Compares the current object with another object of the same type. See the type documentation for a description of ordering semantics.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public int CompareTo(Instant64 other)
Parameters
Type Name Description
Instant64 other An object to compare with this object.
Returns
Type Description
int A 32-bit signed integer that indicates the relative order of the objects being compared. The return value has the following meanings:
ValueMeaning
< 0This object is less than the other parameter.
0This object is equal to other.
> 0This object is greater than other.

Equals(Instant64)

Indicates whether the value of this instant is equal to the value of the specified instant. See the type documentation for a description of equality semantics.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public bool Equals(Instant64 other)
Parameters
Type Name Description
Instant64 other The value to compare with this instance.
Returns
Type Description
bool true if the value of this instant is equal to the value of the other parameter; otherwise, false.

Equals(object?)

Determines whether the specified object is equal to this instance. See the type documentation for a description of equality semantics.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public override bool Equals(object? obj)
Parameters
Type Name Description
object obj The object to compare with this instance.
Returns
Type Description
bool true if the specified object is equal to this instance; otherwise, false.
Overrides

FromDateTimeOffset(DateTimeOffset)

Converts a DateTimeOffset into a new instant representing the same instant in time. Note that the offset information is not preserved in the returned instant.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static Instant64 FromDateTimeOffset(DateTimeOffset dateTimeOffset)
Parameters
Type Name Description
DateTimeOffset dateTimeOffset Date and time value with an offset.
Returns
Type Description
Instant64 An Instant64 value representing the same instant in time as the given DateTimeOffset.
Exceptions
Type Condition
OverflowException dateTimeOffset is outside the range of Instant64.

FromDateTimeUtc(DateTime)

Converts a DateTime into a new instant representing the same instant in time.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static Instant64 FromDateTimeUtc(DateTime dateTime)
Parameters
Type Name Description
DateTime dateTime Date and time value which must have a Kind of Utc
Returns
Type Description
Instant64 An Instant64 value representing the same instant in time as the given universal DateTime.
Exceptions
Type Condition
ArgumentException dateTime is not of Kind dateTime is outside the range of . Utc.

FromInstant(Instant)

Creates an Instant64 value representing the same instant in time as the specified Instant. When this succeeds, this conversion loses no information. If the specified value is outside the range of Instant64, this method will fail with an OverflowException.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static Instant64 FromInstant(Instant instant)
Parameters
Type Name Description
Instant instant The value to convert to a Instant64.
Returns
Type Description
Instant64 An Instant64 value equivalent to instant.
Exceptions
Type Condition
OverflowException instant has a value outside the range of Instant64.

FromUnixTimeMilliseconds(long)

Initializes a new instance of the Instant64 struct based on a number of milliseconds since the Unix epoch of (ISO) January 1st 1970, midnight, UTC.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static Instant64 FromUnixTimeMilliseconds(long milliseconds)
Parameters
Type Name Description
long milliseconds Number of milliseconds since the Unix epoch. May be negative (for instants before the epoch).
Returns
Type Description
Instant64 An Instant64 at exactly the given number of milliseconds since the Unix epoch.
Exceptions
Type Condition
OverflowException The constructed instant would be out of the representable range.

FromUnixTimeNanoseconds(long)

Initializes a new instance of the Instant64 struct based on a number of nanoseconds since the Unix epoch of (ISO) January 1st 1970, midnight, UTC.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static Instant64 FromUnixTimeNanoseconds(long nanoseconds)
Parameters
Type Name Description
long nanoseconds Number of nanoseconds since the Unix epoch. May be negative (for instants before the epoch).
Returns
Type Description
Instant64 An Instant64 at exactly the given number of seconds since the Unix epoch.

FromUnixTimeSeconds(long)

Initializes a new instance of the Instant64 struct based on a number of seconds since the Unix epoch of (ISO) January 1st 1970, midnight, UTC.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static Instant64 FromUnixTimeSeconds(long seconds)
Parameters
Type Name Description
long seconds Number of seconds since the Unix epoch. May be negative (for instants before the epoch).
Returns
Type Description
Instant64 An Instant64 at exactly the given number of seconds since the Unix epoch.
Exceptions
Type Condition
OverflowException The constructed instant would be out of the representable range.

FromUnixTimeTicks(long)

Initializes a new instance of the Instant64 struct based on a number of ticks since the Unix epoch of (ISO) January 1st 1970, midnight, UTC.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static Instant64 FromUnixTimeTicks(long ticks)
Parameters
Type Name Description
long ticks Number of ticks since the Unix epoch. May be negative (for instants before the epoch).
Returns
Type Description
Instant64 An Instant64 at exactly the given number of ticks since the Unix epoch.
Exceptions
Type Condition
OverflowException The constructed instant would be out of the representable range.

FromUtc(int, int, int, int, int)

Returns a new instant corresponding to the given UTC date and time in the ISO calendar.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static Instant64 FromUtc(int year, int monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour)
Parameters
Type Name Description
int year The year. This is the "absolute year", so a value of 0 means 1 BC, for example.
int monthOfYear The month of year.
int dayOfMonth The day of month.
int hourOfDay The hour.
int minuteOfHour The minute.
Returns
Type Description
Instant64 An Instant64 value representing the given date and time in UTC and the ISO calendar.

FromUtc(int, int, int, int, int, int)

Returns a new instant corresponding to the given UTC date and time in the ISO calendar.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static Instant64 FromUtc(int year, int monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, int secondOfMinute)
Parameters
Type Name Description
int year The year. This is the "absolute year", so a value of 0 means 1 BC, for example.
int monthOfYear The month of year.
int dayOfMonth The day of month.
int hourOfDay The hour.
int minuteOfHour The minute.
int secondOfMinute The second.
Returns
Type Description
Instant64 An Instant64 value representing the given date and time in UTC and the ISO calendar.

GetHashCode()

Returns a hash code for this instance. See the type documentation for a description of equality semantics.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public override int GetHashCode()
Returns
Type Description
int A hash code for this instance, suitable for use in hashing algorithms and data structures like a hash table.
Overrides

Max(Instant64, Instant64)

Returns the later instant of the given two.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static Instant64 Max(Instant64 x, Instant64 y)
Parameters
Type Name Description
Instant64 x The first instant to compare.
Instant64 y The second instant to compare.
Returns
Type Description
Instant64 The later instant of x or y.

Min(Instant64, Instant64)

Returns the earlier instant of the given two.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static Instant64 Min(Instant64 x, Instant64 y)
Parameters
Type Name Description
Instant64 x The first instant to compare.
Instant64 y The second instant to compare.
Returns
Type Description
Instant64 The earlier instant of x or y.

Minus(Duration64)

Returns the result of subtracting a duration from this instant, for a fluent alternative to operator-().
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public Instant64 Minus(Duration64 duration)
Parameters
Type Name Description
Duration64 duration The duration to subtract
Returns
Type Description
Instant64 A new Instant64 representing the result of the subtraction.

Minus(Instant64)

Returns the result of subtracting another instant from this one, for a fluent alternative to operator-().
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public Duration64 Minus(Instant64 other)
Parameters
Type Name Description
Instant64 other The other instant to subtract
Returns
Type Description
Duration64 A new Instant64 representing the result of the subtraction.

Plus(Duration64)

Returns the result of adding a duration to this instant, for a fluent alternative to operator+().
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public Instant64 Plus(Duration64 duration)
Parameters
Type Name Description
Duration64 duration The duration to add
Returns
Type Description
Instant64 A new Instant64 representing the result of the addition.

PlusNanoseconds(long)

Returns a new value of this instant with the given number of nanoseconds added to it.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public Instant64 PlusNanoseconds(long nanoseconds)
Parameters
Type Name Description
long nanoseconds The nanoseconds to add to this instant to create the return value.
Returns
Type Description
Instant64 The result of adding the given number of ticks to this instant.

PlusTicks(long)

Returns a new value of this instant with the given number of ticks added to it.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public Instant64 PlusTicks(long ticks)
Parameters
Type Name Description
long ticks The ticks to add to this instant to create the return value.
Returns
Type Description
Instant64 The result of adding the given number of ticks to this instant.

Subtract(Instant64, Duration64)

Subtracts a duration from an instant. Friendly alternative to operator-().
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static Instant64 Subtract(Instant64 left, Duration64 right)
Parameters
Type Name Description
Instant64 left The left hand side of the operator.
Duration64 right The right hand side of the operator.
Returns
Type Description
Instant64 A new Instant64 representing the difference of the given values.

Subtract(Instant64, Instant64)

Subtracts one instant from another. Friendly alternative to operator-().
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static Duration64 Subtract(Instant64 left, Instant64 right)
Parameters
Type Name Description
Instant64 left The left hand side of the operator.
Instant64 right The right hand side of the operator.
Returns
Type Description
Duration64 A new Duration64 representing the difference of the given values.

ToDateTimeOffset()

Constructs a DateTimeOffset from this instant which has an offset of zero.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public DateTimeOffset ToDateTimeOffset()
Returns
Type Description
DateTimeOffset A DateTimeOffset representing the same instant in time as this value.
Remarks

If the date and time is not on a tick boundary (the unit of granularity of DateTime) the value will be truncated towards the start of time. Note that this means the result of calling this method on MinValue is a value which is out of range for FromDateTimeOffset(DateTimeOffset).

ToDateTimeUtc()

Constructs a DateTime from this instant which has a Kind of Utc and represents the same instant of time as this value.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public DateTime ToDateTimeUtc()
Returns
Type Description
DateTime A DateTime representing the same instant in time as this value, with a kind of "universal".
Remarks

If the date and time is not on a tick boundary (the unit of granularity of DateTime) the value will be truncated towards the start of time. Note that this means the result of calling this method on MinValue is a value which is out of range for FromDateTimeUtc(DateTime).

ToInstant()

Converts this value to an Instant representing the same instant in time. This operation always succeeds and loses no information.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public Instant ToInstant()
Returns
Type Description
Instant An Instant representing the same instant in time as this one.

ToString()

Returns a string that represents this instance.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public override string ToString()
Returns
Type Description
string The value of the current instance, converted to an Instant, in the default format pattern ("g"), using the current thread's culture to obtain a format provider.
Overrides

ToString(string?, IFormatProvider?)

Formats the value of the current instance, converted to an Instant, using the specified pattern.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public string ToString(string? patternText, IFormatProvider? formatProvider)
Parameters
Type Name Description
string patternText The string specifying the pattern to use, or null to use the default format pattern ("g").
IFormatProvider formatProvider The IFormatProvider to use when formatting the value, or null to use the current thread's culture to obtain a format provider.
Returns
Type Description
string A string containing the value of the current instance in the specified format.

ToUnixTimeMilliseconds()

Gets the number of milliseconds since the Unix epoch. Negative values represent instants before the Unix epoch.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public long ToUnixTimeMilliseconds()
Returns
Type Description
long The number of milliseconds since the Unix epoch.
Remarks
If the number of nanoseconds in this instant is not an exact number of milliseconds, the value is truncated towards the start of time.

ToUnixTimeNanoseconds()

Gets the number of nanoseconds since the Unix epoch. Negative values represent instants before the Unix epoch.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public long ToUnixTimeNanoseconds()
Returns
Type Description
long The number of ticks since the Unix epoch.

ToUnixTimeSeconds()

Gets the number of seconds since the Unix epoch. Negative values represent instants before the Unix epoch.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public long ToUnixTimeSeconds()
Returns
Type Description
long The number of seconds since the Unix epoch.
Remarks
If the number of nanoseconds in this instant is not an exact number of seconds, the value is truncated towards the start of time.

ToUnixTimeSecondsAndNanoseconds()

Gets the number of seconds since the Unix epoch, along with remaining nanoseconds. Negative values for seconds represent instants before the Unix epoch.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public (long seconds, int nanoseconds) ToUnixTimeSecondsAndNanoseconds()
Returns
Type Description
(long seconds, int nanoseconds) The number of seconds and remaining nanoseconds since the Unix epoch.
Remarks

If the number of nanoseconds in this instant is not an exact number of seconds the seconds part of the returned value is truncated towards the start of time, ensuring that the nanoseconds part is always non-negative. The seconds part of the returned value is always the same as would be returned by ToUnixTimeSeconds().

The inverse of this operation is to first call FromUnixTimeSeconds(long) and then call PlusNanoseconds(long) on the returned Instant64.

ToUnixTimeTicks()

Gets the number of ticks since the Unix epoch. Negative values represent instants before the Unix epoch.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public long ToUnixTimeTicks()
Returns
Type Description
long The number of ticks since the Unix epoch.
Remarks
A tick is equal to 100 nanoseconds. There are 10,000 ticks in a millisecond. If the number of nanoseconds in this instant is not an exact number of ticks, the value is truncated towards the start of time.

Operators

operator +(Instant64, Duration64)

Implements the operator + (addition) for Instant64 + Duration64.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static Instant64 operator +(Instant64 left, Duration64 right)
Parameters
Type Name Description
Instant64 left The left hand side of the operator.
Duration64 right The right hand side of the operator.
Returns
Type Description
Instant64 A new Instant64 representing the sum of the given values.

operator ==(Instant64, Instant64)

Implements the operator == (equality). See the type documentation for a description of equality semantics.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static bool operator ==(Instant64 left, Instant64 right)
Parameters
Type Name Description
Instant64 left The left hand side of the operator.
Instant64 right The right hand side of the operator.
Returns
Type Description
bool true if values are equal to each other, otherwise false.

operator >(Instant64, Instant64)

Implements the operator > (greater than). See the type documentation for a description of ordering semantics.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static bool operator >(Instant64 left, Instant64 right)
Parameters
Type Name Description
Instant64 left The left hand side of the operator.
Instant64 right The right hand side of the operator.
Returns
Type Description
bool true if the left value is greater than the right value, otherwise false.

operator >=(Instant64, Instant64)

Implements the operator >= (greater than or equal). See the type documentation for a description of ordering semantics.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static bool operator >=(Instant64 left, Instant64 right)
Parameters
Type Name Description
Instant64 left The left hand side of the operator.
Instant64 right The right hand side of the operator.
Returns
Type Description
bool true if the left value is greater than or equal to the right value, otherwise false.

operator !=(Instant64, Instant64)

Implements the operator != (inequality). See the type documentation for a description of equality semantics.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static bool operator !=(Instant64 left, Instant64 right)
Parameters
Type Name Description
Instant64 left The left hand side of the operator.
Instant64 right The right hand side of the operator.
Returns
Type Description
bool true if values are not equal to each other, otherwise false.

operator <(Instant64, Instant64)

Implements the operator < (less than). See the type documentation for a description of ordering semantics.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static bool operator <(Instant64 left, Instant64 right)
Parameters
Type Name Description
Instant64 left The left hand side of the operator.
Instant64 right The right hand side of the operator.
Returns
Type Description
bool true if the left value is less than the right value, otherwise false.

operator <=(Instant64, Instant64)

Implements the operator <= (less than or equal). See the type documentation for a description of ordering semantics.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static bool operator <=(Instant64 left, Instant64 right)
Parameters
Type Name Description
Instant64 left The left hand side of the operator.
Instant64 right The right hand side of the operator.
Returns
Type Description
bool true if the left value is less than or equal to the right value, otherwise false.

operator -(Instant64, Duration64)

Implements the operator - (subtraction) for Instant64 - Duration64.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static Instant64 operator -(Instant64 left, Duration64 right)
Parameters
Type Name Description
Instant64 left The left hand side of the operator.
Duration64 right The right hand side of the operator.
Returns
Type Description
Instant64 A new Instant64 representing the difference of the given values.

operator -(Instant64, Instant64)

Implements the operator - (subtraction) for Instant64 - Instant64.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
public static Duration64 operator -(Instant64 left, Instant64 right)
Parameters
Type Name Description
Instant64 left The left hand side of the operator.
Instant64 right The right hand side of the operator.
Returns
Type Description
Duration64 A new Duration64 representing the difference of the given values.

Explicit Interface Implementations

IComparable.CompareTo(object?)

Implementation of CompareTo(object) to compare two instants. See the type documentation for a description of ordering semantics.
Since 3.3.x
Availability net8.0, netstandard2.0
Declaration
int IComparable.CompareTo(object? obj)
Parameters
Type Name Description
object obj The object to compare this value with.
Returns
Type Description
int The result of comparing this instant with another one; see CompareTo(Instant64) for general details. If obj is null, this method returns a value greater than 0.
Remarks
This uses explicit interface implementation to avoid it being called accidentally. The generic implementation should usually be preferred.
Exceptions
Type Condition
ArgumentException obj is non-null but does not refer to an instance of Instant64.

Implements