Struct ZonedDateTime

A LocalDateTime in a specific time zone and with a particular offset to distinguish between otherwise-ambiguous instants. A ZonedDateTime is global, in that it maps to a single Instant.
Since 1.0.x
Availability net35-Client, PCL
Implements
IEquatable<ZonedDateTime>
IComparable<ZonedDateTime>
IComparable
Inherited Members
Object.Equals(Object, Object)
Object.ReferenceEquals(Object, Object)
Object.GetType()
Namespace: NodaTime
Assembly: NodaTime.dll
Syntax
public struct ZonedDateTime : IEquatable<ZonedDateTime>, IComparable<ZonedDateTime>, IComparable
Remarks

Although ZonedDateTime includes both local and global concepts, it only supports duration-based - and not calendar-based - arithmetic. This avoids ambiguities and skipped date/time values becoming a problem within a series of calculations; instead, these can be considered just once, at the point of conversion to a ZonedDateTime.

Comparisons of values can be handled in a way which is either calendar and zone sensitive or insensitive. Noda Time implements all the operators (and the Equals(ZonedDateTime) method) such that all operators other than Inequality(ZonedDateTime, ZonedDateTime) will return false if asked to compare two values in different calendar systems or time zones.

However, the CompareTo(ZonedDateTime) method (implementing System.IComparable<T>) is calendar and zone insensitive; it compares the two global instants in terms of when they actually occurred.

It's unclear at the time of this writing whether this is the most appropriate approach, and it may change in future versions. In general, it would be a good idea for users to avoid comparing dates in different calendar systems, and indeed most users are unlikely to ever explicitly consider which calendar system they're working in anyway.

Currently there is no real text handling support for this type.

Constructors

ZonedDateTime(Instant, DateTimeZone)

Initializes a new instance of the ZonedDateTime struct in the specified time zone and the ISO calendar.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public ZonedDateTime(Instant instant, DateTimeZone zone)
Parameters
Type Name Description
Instant instant The instant.
DateTimeZone zone The time zone.

ZonedDateTime(Instant, DateTimeZone, CalendarSystem)

Initializes a new instance of the ZonedDateTime struct.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public ZonedDateTime(Instant instant, DateTimeZone zone, CalendarSystem calendar)
Parameters
Type Name Description
Instant instant The instant.
DateTimeZone zone The time zone.
CalendarSystem calendar The calendar system.
Exceptions
Type Condition
System.ArgumentNullException zone or calendar is null.

ZonedDateTime(LocalDateTime, DateTimeZone, Offset)

Initializes a new instance of the ZonedDateTime struct in the specified time zone from a given local time and offset. The offset is validated to be correct as part of initialization. In most cases a local time can only map to a single instant anyway, but the offset is included here for cases where the local time is ambiguous, usually due to daylight saving transitions.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public ZonedDateTime(LocalDateTime localDateTime, DateTimeZone zone, Offset offset)
Parameters
Type Name Description
LocalDateTime localDateTime The local date and time.
DateTimeZone zone The time zone.
Offset offset The offset between UTC and local time at the desired instant.
Exceptions
Type Condition
System.ArgumentNullException zone is null
ArgumentException offset is not a valid offset at the given local date and time

Properties

CenturyOfEra

Gets the century within the era of this zoned date and time.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int CenturyOfEra { get; }
Property Value
Type Description
Int32

ClockHourOfHalfDay

Gets the hour of the half-day of this zoned date and time, in the range 1 to 12 inclusive.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int ClockHourOfHalfDay { get; }
Property Value
Type Description
Int32

Date

Gets the local date represented by this zoned date and time. The returned LocalDate will have the same calendar system and return the same values for each of the date-based calendar properties (Year, MonthOfYear and so on), but will not be associated with any particular time zone.
Since 1.1.x
Availability net35-Client, PCL
Declaration
public LocalDate Date { get; }
Property Value
Type Description
LocalDate

Day

Gets the day of this zoned date and time within the month.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int Day { get; }
Property Value
Type Description
Int32

DayOfWeek

Gets the week day of this zoned date and time as a number.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int DayOfWeek { get; }
Property Value
Type Description
Int32
Remarks
For calendars using ISO week days, this gives 1 for Monday to 7 for Sunday.
See Also

DayOfYear

Gets the day of this zoned date and time within the year.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int DayOfYear { get; }
Property Value
Type Description
Int32

Era

Gets the era for this zoned date and time.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public Era Era { get; }
Property Value
Type Description
Era

Hour

Gets the hour of day of this zoned date and time, in the range 0 to 23 inclusive.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int Hour { get; }
Property Value
Type Description
Int32

IsoDayOfWeek

Gets the week day of this zoned date and time expressed as an IsoDayOfWeek value, for calendars which use ISO days of the week.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public IsoDayOfWeek IsoDayOfWeek { get; }
Property Value
Type Description
IsoDayOfWeek
Exceptions
Type Condition
System.InvalidOperationException The underlying calendar doesn't use ISO days of the week.
See Also

LocalDateTime

Gets the local date and time represented by this zoned date and time. The returned LocalDateTime will have the same calendar system and return the same values for each of the calendar properties (Year, MonthOfYear and so on), but will not be associated with any particular time zone.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public LocalDateTime LocalDateTime { get; }
Property Value
Type Description
LocalDateTime

Millisecond

Gets the millisecond of this zoned date and time within the second, in the range 0 to 999 inclusive.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int Millisecond { get; }
Property Value
Type Description
Int32

Minute

Gets the minute of this zoned date and time, in the range 0 to 59 inclusive.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int Minute { get; }
Property Value
Type Description
Int32

Month

Gets the month of this zoned date and time within the year.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int Month { get; }
Property Value
Type Description
Int32

Offset

Gets the offset of the local representation of this value from UTC.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public Offset Offset { get; }
Property Value
Type Description
Offset

Second

Gets the second of this zoned date and time within the minute, in the range 0 to 59 inclusive.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int Second { get; }
Property Value
Type Description
Int32

TickOfDay

Gets the tick of this zoned date and time within the day, in the range 0 to 863,999,999,999 inclusive.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public long TickOfDay { get; }
Property Value
Type Description
Int64

TickOfSecond

Gets the tick of this zoned date and time within the second, in the range 0 to 9,999,999 inclusive.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int TickOfSecond { get; }
Property Value
Type Description
Int32

TimeOfDay

Gets the time portion of this zoned date and time. The returned LocalTime will return the same values for each of the time-based properties (Hour, Minute an so on), but will not be associated with any particular time zone.
Since 1.1.x
Availability net35-Client, PCL
Declaration
public LocalTime TimeOfDay { get; }
Property Value
Type Description
LocalTime

WeekOfWeekYear

Gets the week within the WeekYear. See WeekYear for more details.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int WeekOfWeekYear { get; }
Property Value
Type Description
Int32

WeekYear

Gets the "week year" of this date and time.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int WeekYear { get; }
Property Value
Type Description
Int32
Remarks

The WeekYear is the year that matches with the WeekOfWeekYear field. In the standard ISO-8601 week algorithm, the first week of the year is that in which at least 4 days are in the year. As a result of this definition, day 1 of the first week may be in the previous year. The WeekYear allows you to query the effective year for that day.

For example, January 1st 2011 was a Saturday, so only two days of that week (Saturday and Sunday) were in 2011. Therefore January 1st is part of week 52 of WeekYear 2010. Conversely, December 31st 2012 is a Monday, so is part of week 1 of WeekYear 2013.

Year

Gets the year of this zoned date and time.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int Year { get; }
Property Value
Type Description
Int32
Remarks
This returns the "absolute year", so, for the ISO calendar, a value of 0 means 1 BC, for example.

YearOfCentury

Gets the year of this zoned date and time within its century.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int YearOfCentury { get; }
Property Value
Type Description
Int32
Remarks
This always returns a value in the range 0 to 99 inclusive.

YearOfEra

Gets the year of this zoned date and time within its era.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int YearOfEra { get; }
Property Value
Type Description
Int32

Zone

Gets the time zone associated with this value.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public DateTimeZone Zone { get; }
Property Value
Type Description
DateTimeZone

Methods

Add(ZonedDateTime, Duration)

Adds a duration to a zoned date and time. Friendly alternative to operator+().
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static ZonedDateTime Add(ZonedDateTime zonedDateTime, Duration duration)
Parameters
Type Name Description
ZonedDateTime zonedDateTime The value to add the duration to.
Duration duration The duration to add
Returns
Type Description
ZonedDateTime A new value with the time advanced by the given duration, in the same calendar system and time zone.

CompareTo(ZonedDateTime)

Indicates whether this date/time is earlier, later or the same as another one.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public int CompareTo(ZonedDateTime other)
Parameters
Type Name Description
ZonedDateTime other The other zoned date/time to compare this one with
Returns
Type Description
Int32 A value less than zero if the instant represented by this zoned date/time is earlier than the one in other; zero if the instant is the same as the one in other; a value greater than zero if the instant is later than the one in other.
Remarks
This is purely done in terms of the instant represented; the calendar system and time zone are ignored.

Equals(ZonedDateTime)

Indicates whether the current object is equal to another object of the same type.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public bool Equals(ZonedDateTime other)
Parameters
Type Name Description
ZonedDateTime other An object to compare with this object.
Returns
Type Description
Boolean true if the current object is equal to the other parameter; otherwise, false.

Equals(Object)

Indicates whether this instance and a specified object are equal.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public override bool Equals(object obj)
Parameters
Type Name Description
Object obj Another object to compare to.
Returns
Type Description
Boolean true if obj and this instance are the same type and represent the same value; otherwise, false.
Overrides
System.ValueType.Equals(System.Object)

FromDateTimeOffset(DateTimeOffset)

Returns a new ZonedDateTime representing the same instant in time as the given System.DateTimeOffset. The time zone used will be a fixed time zone, which uses the same offset throughout time.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static ZonedDateTime FromDateTimeOffset(DateTimeOffset dateTimeOffset)
Parameters
Type Name Description
DateTimeOffset dateTimeOffset Date and time value with an offset.
Returns
Type Description
ZonedDateTime A ZonedDateTime value representing the same instant in time as the given System.DateTimeOffset.

GetHashCode()

Computes the hash code for this instance.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public override int GetHashCode()
Returns
Type Description
Int32 A 32-bit signed integer that is the hash code for this instance.
Overrides
System.ValueType.GetHashCode()

Minus(Duration)

Returns the result of subtracting a duration from this zoned date and time, for a fluent alternative to operator-().
Since 1.0.x
Availability net35-Client, PCL
Declaration
public ZonedDateTime Minus(Duration duration)
Parameters
Type Name Description
Duration duration The duration to subtract
Returns
Type Description
ZonedDateTime A new ZonedDateTime representing the result of the subtraction.

Plus(Duration)

Returns the result of adding a duration to this zoned date and time, for a fluent alternative to operator+().
Since 1.0.x
Availability net35-Client, PCL
Declaration
public ZonedDateTime Plus(Duration duration)
Parameters
Type Name Description
Duration duration The duration to add
Returns
Type Description
ZonedDateTime A new ZonedDateTime representing the result of the addition.

Subtract(ZonedDateTime, Duration)

Subtracts a duration from a zoned date and time. Friendly alternative to operator-().
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static ZonedDateTime Subtract(ZonedDateTime zonedDateTime, Duration duration)
Parameters
Type Name Description
ZonedDateTime zonedDateTime The value to subtract the duration from.
Duration duration The duration to subtract.
Returns
Type Description
ZonedDateTime A new value with the time "rewound" by the given duration, in the same calendar system and time zone.

ToDateTimeOffset()

Constructs a System.DateTimeOffset value with the same local time and offset from UTC as this value.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public DateTimeOffset ToDateTimeOffset()
Returns
Type Description
DateTimeOffset A System.DateTimeOffset representation of this value.
Remarks
An offset does not convey as much information as a time zone; a System.DateTimeOffset represents an instant in time along with an associated local time, but it doesn't allow you to find out what the local time would be for another instant.

ToDateTimeUnspecified()

Constructs a System.DateTime from this ZonedDateTime which has a System.DateTime.Kind of System.DateTimeKind.Unspecified and represents the same local time as this value rather than the same instant in time.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public DateTime ToDateTimeUnspecified()
Returns
Type Description
DateTime A System.DateTime representation of this value with an "unspecified" kind, with the same local date and time as this value.
Remarks
System.DateTimeKind.Unspecified is slightly odd - it can be treated as UTC if you use System.DateTime.ToLocalTime or as system local time if you use System.DateTime.ToUniversalTime, but it's the only kind which allows you to construct a System.DateTimeOffset with an arbitrary offset.

ToDateTimeUtc()

Constructs a System.DateTime from this ZonedDateTime which has a System.DateTime.Kind of System.DateTimeKind.Utc and represents the same instant of time as this value rather than the same local time.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public DateTime ToDateTimeUtc()
Returns
Type Description
DateTime A System.DateTime representation of this value with a "universal" kind, with the same instant of time as this value.

ToInstant()

Converts this value to the instant it represents on the time line.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public Instant ToInstant()
Returns
Type Description
Instant The instant corresponding to this value.
Remarks
This is always an unambiguous conversion. Any difficulties due to daylight saving transitions or other changes in time zone are handled when converting from a LocalDateTime to a ZonedDateTime; the ZonedDateTime remembers the actual offset from UTC to local time, so it always knows the exact instant represented.

ToOffsetDateTime()

Constructs an OffsetDateTime with the same local date and time, and the same offset as this zoned date and time, effectively just "removing" the time zone itself.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public OffsetDateTime ToOffsetDateTime()
Returns
Type Description
OffsetDateTime An OffsetDateTime with the same local date/time and offset as this value.

ToString()

Currently returns a string representation of this value indicating the local time, offset and time zone separately. The default ToString method of each component is used, which will render the local time and offset in the "general" pattern for the current thread's culture, and simply include the ID for most time zone implementations.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public override string ToString()
Returns
Type Description
String A string representation of this value.
Overrides
System.ValueType.ToString()
Remarks

This representation is a temporary measure until full support for parsing and formatting ZonedDateTime values is implemented. It is provided in order to make diagnostics simpler, but is likely to be changed in future releases.

WithZone(DateTimeZone)

Creates a new ZonedDateTime representing the same instant in time, in the same calendar but a different time zone.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public ZonedDateTime WithZone(DateTimeZone targetZone)
Parameters
Type Name Description
DateTimeZone targetZone The target time zone to convert to.
Returns
Type Description
ZonedDateTime A new value in the target time zone.
Exceptions
Type Condition
System.ArgumentNullException targetZone is null.

Operators

Addition(ZonedDateTime, Duration)

Returns a new ZonedDateTime with the time advanced by the given duration. Note that due to daylight saving time changes this may not advance the local time by the same amount.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static ZonedDateTime operator +(ZonedDateTime zonedDateTime, Duration duration)
Parameters
Type Name Description
ZonedDateTime zonedDateTime The ZonedDateTime to add the duration to.
Duration duration The duration to add.
Returns
Type Description
ZonedDateTime A new value with the time advanced by the given duration, in the same calendar system and time zone.
Remarks
The returned value retains the calendar system and time zone of the ZonedDateTime.

Equality(ZonedDateTime, ZonedDateTime)

Implements the operator ==.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static bool operator ==(ZonedDateTime left, ZonedDateTime right)
Parameters
Type Name Description
ZonedDateTime left The first value to compare
ZonedDateTime right The second value to compare
Returns
Type Description
Boolean True if the two operands are equal according to Equals(ZonedDateTime); false otherwise

GreaterThan(ZonedDateTime, ZonedDateTime)

Compares two ZonedDateTime values to see if the left one is strictly later than the right one.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static bool operator>(ZonedDateTime lhs, ZonedDateTime rhs)
Parameters
Type Name Description
ZonedDateTime lhs First operand of the comparison
ZonedDateTime rhs Second operand of the comparison
Returns
Type Description
Boolean true if the lhs is strictly later than rhs, false otherwise.
Remarks
This operator always returns false if the two operands have different calendars or time zones. See the top-level type documentation for more information about comparisons.

GreaterThanOrEqual(ZonedDateTime, ZonedDateTime)

Compares two ZonedDateTime values to see if the left one is later than or equal to the right one.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static bool operator >=(ZonedDateTime lhs, ZonedDateTime rhs)
Parameters
Type Name Description
ZonedDateTime lhs First operand of the comparison
ZonedDateTime rhs Second operand of the comparison
Returns
Type Description
Boolean true if the lhs is later than or equal to rhs, false otherwise.
Remarks
This operator always returns false if the two operands have different calendars or time zones. See the top-level type documentation for more information about comparisons.

Inequality(ZonedDateTime, ZonedDateTime)

Implements the operator !=.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static bool operator !=(ZonedDateTime left, ZonedDateTime right)
Parameters
Type Name Description
ZonedDateTime left The first value to compare
ZonedDateTime right The second value to compare
Returns
Type Description
Boolean False if the two operands are equal according to Equals(ZonedDateTime); true otherwise

LessThan(ZonedDateTime, ZonedDateTime)

Compares two ZonedDateTime values to see if the left one is strictly earlier than the right one.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static bool operator <(ZonedDateTime lhs, ZonedDateTime rhs)
Parameters
Type Name Description
ZonedDateTime lhs First operand of the comparison
ZonedDateTime rhs Second operand of the comparison
Returns
Type Description
Boolean true if the lhs is strictly earlier than rhs, false otherwise.
Remarks
This operator always returns false if the two operands have different calendars or time zones. See the top-level type documentation for more information about comparisons.

LessThanOrEqual(ZonedDateTime, ZonedDateTime)

Compares two ZonedDateTime values to see if the left one is earlier than or equal to the right one.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static bool operator <=(ZonedDateTime lhs, ZonedDateTime rhs)
Parameters
Type Name Description
ZonedDateTime lhs First operand of the comparison
ZonedDateTime rhs Second operand of the comparison
Returns
Type Description
Boolean true if the lhs is earlier than or equal to rhs, false otherwise.
Remarks
This operator always returns false if the two operands have different calendars or time zones. See the top-level type documentation for more information about comparisons.

Subtraction(ZonedDateTime, Duration)

Returns a new ZonedDateTime with the duration subtracted. Note that due to daylight saving time changes this may not change the local time by the same amount.
Since 1.0.x
Availability net35-Client, PCL
Declaration
public static ZonedDateTime operator -(ZonedDateTime zonedDateTime, Duration duration)
Parameters
Type Name Description
ZonedDateTime zonedDateTime The value to subtract the duration from.
Duration duration The duration to subtract.
Returns
Type Description
ZonedDateTime A new value with the time "rewound" by the given duration, in the same calendar system and time zone.
Remarks
The returned value retains the calendar system and time zone of the ZonedDateTime.

Explicit Interface Implementations

IComparable.CompareTo(Object)

Implementation of System.IComparable.CompareTo(System.Object) to compare two ZonedDateTimes.
Since 1.1.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 ZonedDateTime with another one; see CompareTo(ZonedDateTime) 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 ZonedDateTime.

Implements

System.IEquatable<T>
System.IComparable<T>
System.IComparable