Struct Instant

Represents an instant on the global timeline.

Since 1.0.x

Availability net35-Client, PCL

Implements

IEquatable<Instant>

IComparable<Instant>

IFormattable

IComparable

IXmlSerializable

ISerializable

Inherited Members

Object.Equals(Object, Object)

Object.ReferenceEquals(Object, Object)

Object.GetType()

Namespace: NodaTime

Assembly: NodaTime.dll

Syntax

[Serializable]
public struct Instant : IEquatable<Instant>, IComparable<Instant>, IFormattable, IComparable, IXmlSerializable, ISerializable

Remarks

An instant is defined by an integral number of 'ticks' since the Unix epoch (typically described as January 1st 1970, midnight, UTC, ISO calendar), where a tick is equal to 100 nanoseconds. There are 10,000 ticks in a millisecond.

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

Constructors

Instant(Int64)

Initializes a new instance of the Instant struct.

Since 1.0.x

Availability net35-Client, PCL

Declaration

public Instant(long ticks)

Parameters

Type	Name	Description
Int64	ticks	The number of ticks since the Unix epoch. Negative values represent instants before the Unix epoch.

Remarks

Note that while the Noda Time Instant type and BCL System.DateTime and System.DateTimeOffset types are all defined in terms of a number of ticks, they use different origins: the Noda Time types count ticks from the Unix epoch (the start of 1970 AD), while the BCL types count from the start of 1 AD. This constructor requires the former; to convert from a number-of-ticks since the BCL epoch, construct a System.DateTime first, then use FromDateTimeUtc(DateTime).

Fields

MaxValue

Represents the largest possible Instant.

Since 1.0.x

Availability net35-Client, PCL

Declaration

public static readonly Instant MaxValue

Field Value

Type	Description
Instant

Remarks

Within Noda Time, this is also used to represent 'the end of time'.

MinValue

Represents the smallest possible Instant.

Since 1.0.x

Availability net35-Client, PCL

Declaration

public static readonly Instant MinValue

Field Value

Type	Description
Instant

Remarks

Within Noda Time, this is also used to represent 'the beginning of time'.

Properties

Ticks

The number of ticks since the Unix epoch. Negative values represent instants before the Unix epoch.

Since 1.0.x

Availability net35-Client, PCL

Declaration

public long Ticks { get; }

Property Value

Type	Description
Int64

Remarks

A tick is equal to 100 nanoseconds. There are 10,000 ticks in a millisecond.

Methods

Add(Instant, Duration)

Adds a duration to an instant. Friendly alternative to operator+().

Since 1.0.x

Availability net35-Client, PCL

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.

CompareTo(Instant)

Compares the current object with another object of the same type.

Since 1.0.x

Availability net35-Client, PCL

Declaration

public int CompareTo(Instant other)

Parameters

Type	Name	Description
Instant	other	An object to compare with this object.

Returns

Type	Description
Int32	A 32-bit 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.

Since 1.0.x

Availability net35-Client, PCL

Declaration

public bool Equals(Instant other)

Parameters

Type	Name	Description
Instant	other	The value to compare with this instance.

Returns

Type	Description
Boolean	true if the value of this instant is equal to the value of the other parameter; otherwise, false.

Equals(Object)

Determines whether the specified System.Object is equal to this instance.

Since 1.0.x

Availability net35-Client, PCL

Declaration

public override bool Equals(object obj)

Parameters

Type	Name	Description
Object	obj	The System.Object to compare with this instance.

Returns

Type	Description
Boolean	true if the specified System.Object is equal to this instance; otherwise, false.

Overrides

System.ValueType.Equals(System.Object)

FromDateTimeOffset(DateTimeOffset)

Converts a System.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 net35-Client, PCL

Declaration

public static Instant FromDateTimeOffset(DateTimeOffset dateTimeOffset)

Parameters

Type	Name	Description
DateTimeOffset	dateTimeOffset	Date and time value with an offset.

Returns

Type	Description
Instant	An Instant value representing the same instant in time as the given System.DateTimeOffset.

FromDateTimeUtc(DateTime)

Converts a System.DateTime into a new Instant representing the same instant in time.

Since 1.0.x

Availability net35-Client, PCL

Declaration

public static Instant FromDateTimeUtc(DateTime dateTime)

Parameters

Type	Name	Description
DateTime	dateTime	Date and time value which must have a System.DateTime.Kind of System.DateTimeKind.Utc

Returns

Type	Description
Instant	An Instant value representing the same instant in time as the given universal System.DateTime.

Exceptions

Type	Condition
ArgumentException	dateTime is not of System.DateTime.Kind System.DateTimeKind.Utc.

FromMillisecondsSinceUnixEpoch(Int64)

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.1.x

Availability net35-Client, PCL

Declaration

public static Instant FromMillisecondsSinceUnixEpoch(long milliseconds)

Parameters

Type	Name	Description
Int64	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

Type	Condition
ArgumentOutOfRangeException	The constructed instant would be out of the range representable in Noda Time.

FromSecondsSinceUnixEpoch(Int64)

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.1.x

Availability net35-Client, PCL

Declaration

public static Instant FromSecondsSinceUnixEpoch(long seconds)

Parameters

Type	Name	Description
Int64	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

Type	Condition
ArgumentOutOfRangeException	The constructed instant would be out of the range representable in Noda Time.

FromTicksSinceUnixEpoch(Int64)

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.1.x

Availability net35-Client, PCL

Declaration

public static Instant FromTicksSinceUnixEpoch(long ticks)

Parameters

Type	Name	Description
Int64	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.

Remarks

This is equivalent to calling the constructor directly, but indicates intent more explicitly.

FromUtc(Int32, Int32, Int32, Int32, Int32)

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 net35-Client, PCL

Declaration

public static Instant FromUtc(int year, int monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour)

Parameters

Type	Name	Description
Int32	year	The year. This is the "absolute year", so a value of 0 means 1 BC, for example.
Int32	monthOfYear	The month of year.
Int32	dayOfMonth	The day of month.
Int32	hourOfDay	The hour.
Int32	minuteOfHour	The minute.

Returns

Type	Description
Instant	An Instant value representing the given date and time in UTC and the ISO calendar.

FromUtc(Int32, Int32, Int32, Int32, Int32, Int32)

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 net35-Client, PCL

Declaration

public static Instant FromUtc(int year, int monthOfYear, int dayOfMonth, int hourOfDay, int minuteOfHour, int secondOfMinute)

Parameters

Type	Name	Description
Int32	year	The year. This is the "absolute year", so a value of 0 means 1 BC, for example.
Int32	monthOfYear	The month of year.
Int32	dayOfMonth	The day of month.
Int32	hourOfDay	The hour.
Int32	minuteOfHour	The minute.
Int32	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.

Since 1.0.x

Availability net35-Client, PCL

Declaration

public override int GetHashCode()

Returns

Type	Description
Int32	A hash code for this instance, suitable for use in hashing algorithms and data structures like a hash table.

Overrides

System.ValueType.GetHashCode()

InUtc()

Returns the ZonedDateTime representing the same point in time as this instant, in the UTC time zone and ISO-8601 calendar. This is a shortcut for calling InZone(DateTimeZone) with an argument of Utc.

Since 1.0.x

Availability net35-Client, PCL

Declaration

public ZonedDateTime InUtc()

Returns

Type	Description
ZonedDateTime	A ZonedDateTime for the same instant, in the UTC time zone and the ISO-8601 calendar

InZone(DateTimeZone)

Returns the ZonedDateTime representing the same point in time as this instant, in the specified time zone and ISO-8601 calendar.

Since 1.0.x

Availability net35-Client, PCL

Declaration

public ZonedDateTime InZone(DateTimeZone zone)

Parameters

Type	Name	Description
DateTimeZone	zone	The time zone in which to represent this instant.

Returns

Type	Description
ZonedDateTime	A ZonedDateTime for the same instant, in the given time zone and the ISO-8601 calendar

Exceptions

Type	Condition
ArgumentNullException	zone is null.

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 net35-Client, PCL

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

Type	Description
ZonedDateTime	A ZonedDateTime for the same instant, in the given time zone and calendar

Exceptions

Type	Condition
ArgumentNullException	zone or calendar is null

Max(Instant, Instant)

Returns the later instant of the given two.

Since 1.0.x

Availability net35-Client, PCL

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 net35-Client, PCL

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 net35-Client, PCL

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 net35-Client, PCL

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 net35-Client, PCL

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.

PlusTicks(Int64)

Returns a new value of this instant with the given number of ticks added to it.

Since 1.0.x

Availability net35-Client, PCL

Declaration

public Instant PlusTicks(long ticksToAdd)

Parameters

Type	Name	Description
Int64	ticksToAdd	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 net35-Client, PCL

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 net35-Client, PCL

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 System.DateTimeOffset from this Instant which has an offset of zero.

Since 1.0.x

Availability net35-Client, PCL

Declaration

public DateTimeOffset ToDateTimeOffset()

Returns

Type	Description
DateTimeOffset	A System.DateTimeOffset representing the same instant in time as this value.

ToDateTimeUtc()

Constructs a System.DateTime from this Instant which has a System.DateTime.Kind of System.DateTimeKind.Utc and represents the same instant of time as this value.

Since 1.0.x

Availability net35-Client, PCL

Declaration

public DateTime ToDateTimeUtc()

Returns

Type	Description
DateTime	A System.DateTime representing the same instant in time as this value, with a kind of "universal".

ToString()

Returns a System.String that represents this instance.

Since 1.0.x

Availability net35-Client, PCL

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

System.ValueType.ToString()

ToString(String, IFormatProvider)

Formats the value of the current instance using the specified pattern.

Since 1.0.x

Availability net35-Client, PCL

Declaration

public string ToString(string patternText, IFormatProvider formatProvider)

Parameters

Type	Name	Description
String	patternText	The System.String specifying the pattern to use, or null to use the default format pattern ("g").
IFormatProvider	formatProvider	The System.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 System.String containing the value of the current instance in the specified format.

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 net35-Client, PCL

Declaration

public OffsetDateTime WithOffset(Offset offset)

Parameters

Type	Name	Description
Offset	offset	The offset from UTC with which to represent this instant.

Returns

Type	Description
OffsetDateTime	An OffsetDateTime for the same instant, with the given offset in the ISO calendar system

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 net35-Client, PCL

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

Type	Description
OffsetDateTime	An OffsetDateTime for the same instant, with the given offset and calendar

Exceptions

Type	Condition
ArgumentNullException	calendar is null.

Operators

Addition(Instant, Duration)

Implements the operator + (addition) for Instant + Duration.

Since 1.0.x

Availability net35-Client, PCL

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.

Equality(Instant, Instant)

Implements the operator == (equality).

Since 1.0.x

Availability net35-Client, PCL

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
Boolean	true if values are equal to each other, otherwise false.

GreaterThan(Instant, Instant)

Implements the operator > (greater than).

Since 1.0.x

Availability net35-Client, PCL

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
Boolean	true if the left value is greater than the right value, otherwise false.

GreaterThanOrEqual(Instant, Instant)

Implements the operator >= (greater than or equal).

Since 1.0.x

Availability net35-Client, PCL

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
Boolean	true if the left value is greater than or equal to the right value, otherwise false.

Inequality(Instant, Instant)

Implements the operator != (inequality).

Since 1.0.x

Availability net35-Client, PCL

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
Boolean	true if values are not equal to each other, otherwise false.

LessThan(Instant, Instant)

Implements the operator < (less than).

Since 1.0.x

Availability net35-Client, PCL

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
Boolean	true if the left value is less than the right value, otherwise false.

LessThanOrEqual(Instant, Instant)

Implements the operator <= (less than or equal).

Since 1.0.x

Availability net35-Client, PCL

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
Boolean	true if the left value is less than or equal to the right value, otherwise false.

Subtraction(Instant, Duration)

Implements the operator - (subtraction) for Instant - Duration.

Since 1.0.x

Availability net35-Client, PCL

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.

Subtraction(Instant, Instant)

Implements the operator - (subtraction) for Instant - Instant.

Since 1.0.x

Availability net35-Client, PCL

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 Instant representing the difference of the given values.

Explicit Interface Implementations

IComparable.CompareTo(Object)

Implementation of System.IComparable.CompareTo(System.Object) to compare two instants.

Since 1.0.x

Availability net35-Client, PCL

Declaration

int IComparable.CompareTo(object obj)

Parameters

Type	Name	Description
Object	obj	The object to compare this value with.

Returns

Type	Description
Int32	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.

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 Instant.

ISerializable.GetObjectData(SerializationInfo, StreamingContext)

Implementation of System.Runtime.Serialization.ISerializable.GetObjectData(System.Runtime.Serialization.SerializationInfo, System.Runtime.Serialization.StreamingContext).

Since 1.2.x

Availability net35-Client

Declaration

[SecurityCritical]
void ISerializable.GetObjectData(SerializationInfo info, StreamingContext context)

Parameters

Type	Name	Description
SerializationInfo	info	The System.Runtime.Serialization.SerializationInfo to populate with data.
StreamingContext	context	The destination for this serialization.

IXmlSerializable.GetSchema()

Since 1.2.x

Availability net35-Client, PCL

Declaration

XmlSchema IXmlSerializable.GetSchema()

Returns

Type	Description
XmlSchema

IXmlSerializable.ReadXml(XmlReader)

Since 1.2.x

Availability net35-Client, PCL

Declaration

void IXmlSerializable.ReadXml(XmlReader reader)

Parameters

Type	Name	Description
XmlReader	reader

IXmlSerializable.WriteXml(XmlWriter)

Since 1.2.x

Availability net35-Client, PCL

Declaration

void IXmlSerializable.WriteXml(XmlWriter writer)

Parameters

Type	Name	Description
XmlWriter	writer

Implements

System.IEquatable<T>

System.IComparable<T>

System.IFormattable

System.IComparable

System.Xml.Serialization.IXmlSerializable

System.Runtime.Serialization.ISerializable