Struct Instant
Represents an instant on the global timeline, with nanosecond resolution.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Assembly: NodaTime.dll
Syntax
[TypeConverter(typeof(InstantTypeConverter))]
public readonly struct Instant : IEquatable<Instant>, IComparable<Instant>, IFormattable, IComparable, IXmlSerializable, IAdditionOperators<Instant, Duration, Instant>, ISubtractionOperators<Instant, Duration, Instant>, ISubtractionOperators<Instant, Instant, Duration>, IComparisonOperators<Instant, Instant, bool>, IEqualityOperators<Instant, Instant, bool>, IMinMaxValue<Instant>
Properties
MaxValue
Represents the largest possible
Instant.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Instant MaxValue { get; }
Property Value
MinValue
Represents the smallest possible
Instant.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Instant MinValue { get; }
Property Value
Methods
Add(Instant, Duration)
Adds a duration to an instant. Friendly alternative to operator+()
.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Instant Add(Instant left, Duration right)
Parameters
Type 
Name 
Description 
Instant 
left 
The left hand side of the operator. 
Duration 
right 
The right hand side of the operator. 
Returns
Type 
Description 
Instant 
A new Instant representing the sum of the given values. 
AddSchema(XmlSchemaSet)
Adds the XML schema type describing the structure of the
Instant XML serialization to the given
xmlSchemaSet
.
Since 3.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static XmlQualifiedName AddSchema(XmlSchemaSet xmlSchemaSet)
Parameters
Returns
Type 
Description 
XmlQualifiedName 
The qualified name of the schema type that was added to the xmlSchemaSet . 
CompareTo(Instant)
Compares the current object with another object of the same type.
See the type documentation for a description of ordering semantics.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public int CompareTo(Instant other)
Parameters
Type 
Name 
Description 
Instant 
other 
An object to compare with this object. 
Returns
Type 
Description 
int 
A 32bit signed integer that indicates the relative order of the objects being compared.
The return value has the following meanings:
Value  Meaning 

< 0  This object is less than the other parameter.  0  This object is equal to other .  > 0  This object is greater than other . 

Equals(Instant)
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 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public bool Equals(Instant other)
Parameters
Type 
Name 
Description 
Instant 
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 1.0.x
Availability net6.0, 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 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Instant FromDateTimeOffset(DateTimeOffset dateTimeOffset)
Parameters
Type 
Name 
Description 
DateTimeOffset 
dateTimeOffset 
Date and time value with an offset. 
Returns
FromDateTimeUtc(DateTime)
Converts a
DateTime into a new Instant representing the same instant in time.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Instant FromDateTimeUtc(DateTime dateTime)
Parameters
Type 
Name 
Description 
DateTime 
dateTime 
Date and time value which must have a Kind of Utc 
Returns
Type 
Description 
Instant 
An Instant value representing the same instant in time as the given universal DateTime. 
Exceptions
FromJulianDate(double)
Converts a Julian Date representing the given number of days
since
JulianEpoch (noon on January 1st, 4713 BCE in the Julian calendar)
into an
Instant.
Since 2.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Instant FromJulianDate(double julianDate)
Parameters
Type 
Name 
Description 
double 
julianDate 
The number of days since the Julian Epoch to convert into an Instant. 
Returns
Type 
Description 
Instant 
An Instant value which is julianDate days after the Julian Epoch. 
FromUnixTimeMilliseconds(long)
Initializes a new instance of the
Instant struct based
on a number of milliseconds since the Unix epoch of (ISO) January 1st 1970, midnight, UTC.
Since 1.4.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Instant 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 
Instant 
An Instant at exactly the given number of milliseconds since the Unix epoch. 
Exceptions
FromUnixTimeSeconds(long)
Initializes a new instance of the
Instant struct based
on a number of seconds since the Unix epoch of (ISO) January 1st 1970, midnight, UTC.
Since 1.4.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Instant 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 
Instant 
An Instant at exactly the given number of seconds since the Unix epoch. 
Exceptions
FromUnixTimeTicks(long)
Initializes a new instance of the
Instant struct based
on a number of ticks since the Unix epoch of (ISO) January 1st 1970, midnight, UTC.
Since 1.4.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Instant 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 
Instant 
An Instant at exactly the given number of ticks since the Unix epoch. 
FromUtc(int, int, int, int, int)
Returns a new instant corresponding to the given UTC date and time in the ISO calendar.
In most cases applications should use
ZonedDateTime to represent a date
and time, but this method is useful in some situations where an
Instant is
required, such as time zone testing.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Instant 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 
Instant 
An Instant 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. In most cases applications should
use
ZonedDateTime
to represent a date and time, but this method is useful in some
situations where an Instant is required, such as time zone testing.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Instant 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 
Instant 
An Instant 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 1.0.x
Availability net6.0, 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
InUtc()
Returns the
ZonedDateTime representing the same point in time as this instant, in the UTC time
zone and ISO8601 calendar. This is a shortcut for calling
InZone(DateTimeZone) with an
argument of
Utc.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public ZonedDateTime InUtc()
Returns
InZone(DateTimeZone)
Returns the
ZonedDateTime representing the same point in time as this instant, in the
specified time zone and ISO8601 calendar.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public ZonedDateTime InZone(DateTimeZone zone)
Parameters
Type 
Name 
Description 
DateTimeZone 
zone 
The time zone in which to represent this instant. 
Returns
InZone(DateTimeZone, CalendarSystem)
Returns the
ZonedDateTime representing the same point in time as this instant, in the
specified time zone and calendar system.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public ZonedDateTime InZone(DateTimeZone zone, CalendarSystem calendar)
Parameters
Type 
Name 
Description 
DateTimeZone 
zone 
The time zone in which to represent this instant. 
CalendarSystem 
calendar 
The calendar system in which to represent this instant. 
Returns
Max(Instant, Instant)
Returns the later instant of the given two.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Instant Max(Instant x, Instant y)
Parameters
Type 
Name 
Description 
Instant 
x 
The first instant to compare. 
Instant 
y 
The second instant to compare. 
Returns
Type 
Description 
Instant 
The later instant of x or y . 
Min(Instant, Instant)
Returns the earlier instant of the given two.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Instant Min(Instant x, Instant y)
Parameters
Type 
Name 
Description 
Instant 
x 
The first instant to compare. 
Instant 
y 
The second instant to compare. 
Returns
Type 
Description 
Instant 
The earlier instant of x or y . 
Minus(Duration)
Returns the result of subtracting a duration from this instant, for a fluent alternative to operator()
.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public Instant Minus(Duration duration)
Parameters
Type 
Name 
Description 
Duration 
duration 
The duration to subtract 
Returns
Type 
Description 
Instant 
A new Instant representing the result of the subtraction. 
Minus(Instant)
Returns the result of subtracting another instant from this one, for a fluent alternative to operator()
.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public Duration Minus(Instant other)
Parameters
Type 
Name 
Description 
Instant 
other 
The other instant to subtract 
Returns
Type 
Description 
Duration 
A new Instant representing the result of the subtraction. 
Plus(Duration)
Returns the result of adding a duration to this instant, for a fluent alternative to operator+()
.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public Instant Plus(Duration duration)
Parameters
Type 
Name 
Description 
Duration 
duration 
The duration to add 
Returns
Type 
Description 
Instant 
A new Instant 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 2.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public Instant PlusNanoseconds(long nanoseconds)
Parameters
Type 
Name 
Description 
long 
nanoseconds 
The nanoseconds to add to this instant to create the return value. 
Returns
Type 
Description 
Instant 
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 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public Instant PlusTicks(long ticks)
Parameters
Type 
Name 
Description 
long 
ticks 
The ticks to add to this instant to create the return value. 
Returns
Type 
Description 
Instant 
The result of adding the given number of ticks to this instant. 
Subtract(Instant, Duration)
Subtracts a duration from an instant. Friendly alternative to operator()
.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Instant Subtract(Instant left, Duration right)
Parameters
Type 
Name 
Description 
Instant 
left 
The left hand side of the operator. 
Duration 
right 
The right hand side of the operator. 
Returns
Type 
Description 
Instant 
A new Instant representing the difference of the given values. 
Subtract(Instant, Instant)
Subtracts one instant from another. Friendly alternative to operator()
.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Duration Subtract(Instant left, Instant right)
Parameters
Type 
Name 
Description 
Instant 
left 
The left hand side of the operator. 
Instant 
right 
The right hand side of the operator. 
Returns
Type 
Description 
Duration 
A new Duration representing the difference of the given values. 
ToDateTimeOffset()
Constructs a
DateTimeOffset from this Instant which has an offset of zero.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public DateTimeOffset ToDateTimeOffset()
Returns
Exceptions
ToDateTimeUtc()
Constructs a
DateTime from this Instant which has a
Kind
of
Utc and represents the same instant of time as this value.
Since 1.0.x
Availability net6.0, 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". 
Exceptions
ToJulianDate()
Returns the Julian Date of this instance  the number of days since
JulianEpoch (noon on January 1st, 4713 BCE in the Julian calendar).
Since 2.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public double ToJulianDate()
Returns
Type 
Description 
double 
The number of days (including fractional days) since the Julian Epoch. 
ToString()
Returns a
string that represents this instance.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public override string ToString()
Returns
Type 
Description 
string 
The value of the current instance in the default format pattern ("g"), using the current thread's
culture to obtain a format provider. 
Overrides
Formats the value of the current instance using the specified pattern.
Since 1.0.x
Availability net6.0, 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 2.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public long ToUnixTimeMilliseconds()
Returns
Type 
Description 
long 
The number of milliseconds since the Unix epoch. 
ToUnixTimeSeconds()
Gets the number of seconds since the Unix epoch. Negative values represent instants before the Unix epoch.
Since 2.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public long ToUnixTimeSeconds()
Returns
Type 
Description 
long 
The number of seconds since the Unix epoch. 
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.2.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public (long seconds, int nanoseconds) ToUnixTimeSecondsAndNanoseconds()
Returns
Remarks
ToUnixTimeTicks()
Gets the number of ticks since the Unix epoch. Negative values represent instants before the Unix epoch.
Since 1.4.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public long ToUnixTimeTicks()
Returns
Type 
Description 
long 
The number of ticks since the Unix epoch. 
WithOffset(Offset)
Returns the
OffsetDateTime representing the same point in time as this instant, with
the specified UTC offset in the ISO calendar system.
Since 1.2.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public OffsetDateTime WithOffset(Offset offset)
Parameters
Type 
Name 
Description 
Offset 
offset 
The offset from UTC with which to represent this instant. 
Returns
WithOffset(Offset, CalendarSystem)
Returns the
OffsetDateTime representing the same point in time as this instant, with
the specified UTC offset and calendar system.
Since 1.2.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public OffsetDateTime WithOffset(Offset offset, CalendarSystem calendar)
Parameters
Type 
Name 
Description 
Offset 
offset 
The offset from UTC with which to represent this instant. 
CalendarSystem 
calendar 
The calendar system in which to represent this instant. 
Returns
Operators
operator +(Instant, Duration)
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Instant operator +(Instant left, Duration right)
Parameters
Type 
Name 
Description 
Instant 
left 
The left hand side of the operator. 
Duration 
right 
The right hand side of the operator. 
Returns
Type 
Description 
Instant 
A new Instant representing the sum of the given values. 
operator ==(Instant, Instant)
Implements the operator == (equality).
See the type documentation for a description of equality semantics.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static bool operator ==(Instant left, Instant right)
Parameters
Type 
Name 
Description 
Instant 
left 
The left hand side of the operator. 
Instant 
right 
The right hand side of the operator. 
Returns
Type 
Description 
bool 
true if values are equal to each other, otherwise false . 
operator >(Instant, Instant)
Implements the operator > (greater than).
See the type documentation for a description of ordering semantics.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static bool operator >(Instant left, Instant right)
Parameters
Type 
Name 
Description 
Instant 
left 
The left hand side of the operator. 
Instant 
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 >=(Instant, Instant)
Implements the operator >= (greater than or equal).
See the type documentation for a description of ordering semantics.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static bool operator >=(Instant left, Instant right)
Parameters
Type 
Name 
Description 
Instant 
left 
The left hand side of the operator. 
Instant 
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 !=(Instant, Instant)
Implements the operator != (inequality).
See the type documentation for a description of equality semantics.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static bool operator !=(Instant left, Instant right)
Parameters
Type 
Name 
Description 
Instant 
left 
The left hand side of the operator. 
Instant 
right 
The right hand side of the operator. 
Returns
Type 
Description 
bool 
true if values are not equal to each other, otherwise false . 
operator <(Instant, Instant)
Implements the operator < (less than).
See the type documentation for a description of ordering semantics.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static bool operator <(Instant left, Instant right)
Parameters
Type 
Name 
Description 
Instant 
left 
The left hand side of the operator. 
Instant 
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 <=(Instant, Instant)
Implements the operator <= (less than or equal).
See the type documentation for a description of ordering semantics.
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static bool operator <=(Instant left, Instant right)
Parameters
Type 
Name 
Description 
Instant 
left 
The left hand side of the operator. 
Instant 
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 (Instant, Duration)
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Instant operator (Instant left, Duration right)
Parameters
Type 
Name 
Description 
Instant 
left 
The left hand side of the operator. 
Duration 
right 
The right hand side of the operator. 
Returns
Type 
Description 
Instant 
A new Instant representing the difference of the given values. 
operator (Instant, Instant)
Since 1.0.x
Availability net6.0, net8.0, netstandard2.0
Declaration
public static Duration operator (Instant left, Instant right)
Parameters
Type 
Name 
Description 
Instant 
left 
The left hand side of the operator. 
Instant 
right 
The right hand side of the operator. 
Returns
Type 
Description 
Duration 
A new Duration 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 1.0.x
Availability net6.0, 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(Instant) for general details.
If obj is null, this method returns a value greater than 0. 
Exceptions
IXmlSerializable.GetSchema()
This method is reserved and should not be used. When implementing the
IXmlSerializable
interface, you should return
null (
Nothing
in Visual Basic) from this method, and instead, if specifying a custom schema is required, apply the
XmlSchemaProviderAttribute to the class.
Since 3.2.x
Availability net6.0, net8.0, netstandard2.0
Declaration
XmlSchema IXmlSerializable.GetSchema()
Returns
IXmlSerializable.ReadXml(XmlReader)
Generates an object from its XML representation.
Since 1.2.x
Availability net6.0, net8.0, netstandard2.0
Declaration
void IXmlSerializable.ReadXml(XmlReader reader)
Parameters
Type 
Name 
Description 
XmlReader 
reader 
The XmlReader stream from which the object is deserialized. 
IXmlSerializable.WriteXml(XmlWriter)
Converts an object into its XML representation.
Since 1.2.x
Availability net6.0, net8.0, netstandard2.0
Declaration
void IXmlSerializable.WriteXml(XmlWriter writer)
Parameters
Type 
Name 
Description 
XmlWriter 
writer 
The XmlWriter stream to which the object is serialized. 
Implements