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 net45, netstandard1.3
Inherited Members
Object.Equals(Object, Object)
Object.ReferenceEquals(Object, Object)
Object.GetType()
Namespace: NodaTime
Assembly: NodaTime.dll
Syntax
[Serializable]
public struct ZonedDateTime : IEquatable<ZonedDateTime>, IFormattable, IXmlSerializable, ISerializableRemarks
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.
ZonedDateTime does not implement ordered comparison operators, as there is no obvious natural ordering that works in all cases.
Equality is supported however, requiring equality of zone, calendar and date/time. If you want to sort ZonedDateTime
values, you should explicitly choose one of the orderings provided via the static properties in the
ZonedDateTime.Comparer nested class (or implement your own comparison).
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 net45, netstandard1.3
Declaration
public ZonedDateTime(Instant instant, DateTimeZone zone)Parameters
| Type | Name | Description |
|---|---|---|
| Instant | instant | The instant. |
| DateTimeZone | zone | The time zone. |
Exceptions
| Type | Condition |
|---|---|
| ArgumentNullException | zone is null. |
ZonedDateTime(Instant, DateTimeZone, CalendarSystem)
Initializes a new instance of the ZonedDateTime struct.
Since 1.0.x
Availability net45, netstandard1.3
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 |
|---|---|
| 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 net45, netstandard1.3
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 |
|---|---|
| ArgumentException | offset is not a valid offset at the given
local date and time. |
| ArgumentNullException | zone is null. |
Properties
Calendar
Gets the calendar system associated with this zoned date and time.
Since 1.2.x
Availability net45, netstandard1.3
Declaration
public CalendarSystem Calendar { get; }Property Value
| Type | Description |
|---|---|
| CalendarSystem | The calendar system associated with this zoned date and time. (The value returned is never null.) |
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 net45, netstandard1.3
Declaration
public int ClockHourOfHalfDay { get; }Property Value
| Type | Description |
|---|---|
| Int32 | The hour of the half-day of this zoned date and time, in the range 1 to 12 inclusive. |
Date
Gets the local date represented by this zoned date and time.
Since 1.1.x
Availability net45, netstandard1.3
Declaration
public LocalDate Date { get; }Property Value
| Type | Description |
|---|---|
| LocalDate | The local date represented by this zoned date and time. |
Remarks
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.
Day
Gets the day of this zoned date and time within the month.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public int Day { get; }Property Value
| Type | Description |
|---|---|
| Int32 | The day of this zoned date and time within the month. |
DayOfWeek
Gets the week day of this zoned date and time expressed as an IsoDayOfWeek value.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public IsoDayOfWeek DayOfWeek { get; }Property Value
| Type | Description |
|---|---|
| IsoDayOfWeek | The week day of this zoned date and time expressed as an IsoDayOfWeek value. |
DayOfYear
Gets the day of this zoned date and time within the year.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public int DayOfYear { get; }Property Value
| Type | Description |
|---|---|
| Int32 | The day of this zoned date and time within the year. |
Era
Gets the era for this zoned date and time.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public Era Era { get; }Property Value
| Type | Description |
|---|---|
| Era | The era for this zoned date and time. (The value returned is never null.) |
Hour
Gets the hour of day of this zoned date and time, in the range 0 to 23 inclusive.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public int Hour { get; }Property Value
| Type | Description |
|---|---|
| Int32 | The hour of day of this zoned date and time, in the range 0 to 23 inclusive. |
LocalDateTime
Gets the local date and time represented by this zoned date and time.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public LocalDateTime LocalDateTime { get; }Property Value
| Type | Description |
|---|---|
| LocalDateTime | The local date and time represented by this zoned date and time. |
Remarks
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.
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 net45, netstandard1.3
Declaration
public int Millisecond { get; }Property Value
| Type | Description |
|---|---|
| Int32 | The millisecond of this zoned date and time within the second, in the range 0 to 999 inclusive. |
Minute
Gets the minute of this zoned date and time, in the range 0 to 59 inclusive.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public int Minute { get; }Property Value
| Type | Description |
|---|---|
| Int32 | The minute of this zoned date and time, in the range 0 to 59 inclusive. |
Month
Gets the month of this zoned date and time within the year.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public int Month { get; }Property Value
| Type | Description |
|---|---|
| Int32 | The month of this zoned date and time within the year. |
NanosecondOfDay
Gets the nanosecond of this zoned date and time within the day, in the range 0 to 86,399,999,999,999 inclusive.
Since 2.0.x
Availability net45, netstandard1.3
Declaration
public long NanosecondOfDay { get; }Property Value
| Type | Description |
|---|---|
| Int64 | The nanosecond of this zoned date and time within the day, in the range 0 to 86,399,999,999,999 inclusive. |
Remarks
This is the NanosecondOfDay portion of the contained OffsetDateTime.
On daylight saving time transition dates, it may not be the same as the number of nanoseconds elapsed since the beginning of the day.
Sample snippet
using NodaTime;
using System;
// This is a 25-hour day at the end of daylight saving time
var dt = new LocalDate(2017, 10, 29);
var time = new LocalTime(23, 59, 59);
var dublin = DateTimeZoneProviders.Tzdb["Europe/Dublin"];
var startOfDay = dublin.AtStartOfDay(dt);
ZonedDateTime nearEndOfDay = dublin.AtStrictly(dt + time);
Console.WriteLine(nearEndOfDay.NanosecondOfDay);
Duration duration = nearEndOfDay - startOfDay;
Console.WriteLine(duration);
Output:
86399000000000
1:00:59:59
NanosecondOfSecond
Gets the nanosecond of this zoned date and time within the second, in the range 0 to 999,999,999 inclusive.
Since 2.0.x
Availability net45, netstandard1.3
Declaration
public int NanosecondOfSecond { get; }Property Value
| Type | Description |
|---|---|
| Int32 | The nanosecond of this zoned date and time within the second, in the range 0 to 999,999,999 inclusive. |
Offset
Gets the offset of the local representation of this value from UTC.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public Offset Offset { get; }Property Value
| Type | Description |
|---|---|
| Offset | The offset of the local representation of this value from UTC. |
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 net45, netstandard1.3
Declaration
public int Second { get; }Property Value
| Type | Description |
|---|---|
| Int32 | The second of this zoned date and time within the minute, in the range 0 to 59 inclusive. |
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 net45, netstandard1.3
Declaration
public long TickOfDay { get; }Property Value
| Type | Description |
|---|---|
| Int64 | The tick of this zoned date and time within the day, in the range 0 to 863,999,999,999 inclusive. |
Remarks
This is the TickOfDay portion of the contained OffsetDateTime.
On daylight saving time transition dates, it may not be the same as the number of ticks elapsed since the beginning of the day.
Sample snippet
using NodaTime;
using System;
// This is a 25-hour day at the end of daylight saving time
var dt = new LocalDate(2017, 10, 29);
var time = new LocalTime(23, 59, 59);
var dublin = DateTimeZoneProviders.Tzdb["Europe/Dublin"];
var startOfDay = dublin.AtStartOfDay(dt);
ZonedDateTime nearEndOfDay = dublin.AtStrictly(dt + time);
Console.WriteLine(nearEndOfDay.TickOfDay);
Duration duration = nearEndOfDay - startOfDay;
Console.WriteLine(duration);
Output:
863990000000
1:00:59:59
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 net45, netstandard1.3
Declaration
public int TickOfSecond { get; }Property Value
| Type | Description |
|---|---|
| Int32 | The tick of this zoned date and time within the second, in the range 0 to 9,999,999 inclusive. |
TimeOfDay
Gets the time portion of this zoned date and time.
Since 1.1.x
Availability net45, netstandard1.3
Declaration
public LocalTime TimeOfDay { get; }Property Value
| Type | Description |
|---|---|
| LocalTime | The time portion of this zoned date and time. |
Remarks
The returned LocalTime will
return the same values for each of the time-based properties (Hour, Minute and so on), but
will not be associated with any particular time zone.
Year
Gets the year of this zoned date and time.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public int Year { get; }Property Value
| Type | Description |
|---|---|
| Int32 | The year of this zoned date and time. |
Remarks
This returns the "absolute year", so, for the ISO calendar,
a value of 0 means 1 BC, for example.
YearOfEra
Gets the year of this zoned date and time within its era.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public int YearOfEra { get; }Property Value
| Type | Description |
|---|---|
| Int32 | The year of this zoned date and time within its era. |
Zone
Gets the time zone associated with this value.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public DateTimeZone Zone { get; }Property Value
| Type | Description |
|---|---|
| DateTimeZone | The time zone associated with this value. (The value returned is never null.) |
Methods
Add(ZonedDateTime, Duration)
Adds a duration to a zoned date and time.
Since 1.0.x
Availability net45, netstandard1.3
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. |
Remarks
This is an alternative way of calling Addition(ZonedDateTime, Duration).
Sample snippet
using NodaTime;
using System;
// Europe/Dublin transitions from UTC+1 to UTC+0 at 2am (local) on 2017-10-29
var dt = new LocalDateTime(2017, 10, 29, 1, 45, 0);
DateTimeZone dublin = DateTimeZoneProviders.Tzdb["Europe/Dublin"];
ZonedDateTime beforeTransition = new ZonedDateTime(dt, dublin, Offset.FromHours(1));
var result = ZonedDateTime.Add(beforeTransition, Duration.FromHours(1));
Console.WriteLine(result.Date);
// Adding an hour of elapsed time takes us across the DST transition, so we have
// the same local time (shown on a clock) but a different offset.
Console.WriteLine(result);
// The + operator and Plus instance method are equivalent to the Add static method.
var result2 = beforeTransition + Duration.FromHours(1);
var result3 = beforeTransition.Plus(Duration.FromHours(1));
Console.WriteLine(result2);
Console.WriteLine(result3);
Output:
Sunday, 29 October 2017
2017-10-29T01:45:00 Europe/Dublin (+00)
2017-10-29T01:45:00 Europe/Dublin (+00)
2017-10-29T01:45:00 Europe/Dublin (+00)
Deconstruct(out LocalDateTime, out DateTimeZone, out Offset)
Deconstruct this ZonedDateTime into its components.
Since 2.3.x
Availability net45, netstandard1.3
Declaration
public void Deconstruct(out LocalDateTime localDateTime, out DateTimeZone dateTimeZone, out Offset offset)Parameters
| Type | Name | Description |
|---|---|---|
| LocalDateTime | localDateTime | The LocalDateTime component. |
| DateTimeZone | dateTimeZone | The DateTimeZone component. |
| Offset | offset | The Offset component. |
Equals(ZonedDateTime)
Indicates whether the current object is equal to another object of the same type.
Since 1.0.x
Availability net45, netstandard1.3
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 net45, netstandard1.3
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 net45, netstandard1.3
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 net45, netstandard1.3
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()
GetZoneInterval()
Returns the ZoneInterval containing this value, in the time zone this
value refers to.
Since 1.2.x
Availability net45, netstandard1.3
Declaration
public ZoneInterval GetZoneInterval()Returns
| Type | Description |
|---|---|
| ZoneInterval | The ZoneInterval containing this value. (The value returned is never null.) |
Remarks
This is simply a convenience method - it is logically equivalent to converting this
value to an Instant and then asking the appropriate DateTimeZone
for the
ZoneInterval containing that instant.
IsDaylightSavingTime()
Indicates whether or not this ZonedDateTime is in daylight saving time
for its time zone. This is determined by checking the Savings property
of the zone interval containing this value.
Since 1.3.x
Availability net45, netstandard1.3
Declaration
public bool IsDaylightSavingTime()Returns
| Type | Description |
|---|---|
| Boolean | true if the zone interval containing this value has a non-zero savings
component; false otherwise. |
Sample snippet
using NodaTime;
using System;
// Europe/Dublin transitions from UTC+1 to UTC+0 at 2am (local) on 2017-10-29
var dt = new LocalDateTime(2017, 10, 29, 1, 45, 0);
DateTimeZone dublin = DateTimeZoneProviders.Tzdb["Europe/Dublin"];
ZonedDateTime beforeTransition = new ZonedDateTime(dt, dublin, Offset.FromHours(1));
Console.WriteLine(beforeTransition.IsDaylightSavingTime());
// Same local time, different offset - so a different instant, after the transition.
ZonedDateTime afterTransition = new ZonedDateTime(dt, dublin, Offset.FromHours(0));
Console.WriteLine(afterTransition.IsDaylightSavingTime());
Output:
False
True
See Also
Minus(Duration)
Returns the result of subtracting a duration from this zoned date and time, for a fluent alternative to
Subtraction(ZonedDateTime, Duration)
Since 1.0.x
Availability net45, netstandard1.3
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. |
Sample snippet
using NodaTime;
using System;
// Europe/Dublin transitions from UTC+1 to UTC+0 at 2am (local) on 2017-10-29
var dt = new LocalDateTime(2017, 10, 29, 1, 45, 0);
DateTimeZone dublin = DateTimeZoneProviders.Tzdb["Europe/Dublin"];
ZonedDateTime afterTransition = new ZonedDateTime(dt, dublin, Offset.FromHours(0));
var result = ZonedDateTime.Subtract(afterTransition, Duration.FromHours(1));
Console.WriteLine(result.Date);
// Adding an hour of elapsed time takes us across the DST transition, so we have
// the same local time (shown on a clock) but a different offset.
Console.WriteLine(result);
// The + operator and Plus instance method are equivalent to the Add static method.
var result2 = afterTransition - Duration.FromHours(1);
var result3 = afterTransition.Minus(Duration.FromHours(1));
Console.WriteLine(result2);
Console.WriteLine(result3);
Output:
Sunday, 29 October 2017
2017-10-29T01:45:00 Europe/Dublin (+01)
2017-10-29T01:45:00 Europe/Dublin (+01)
2017-10-29T01:45:00 Europe/Dublin (+01)
Minus(ZonedDateTime)
Returns the result of subtracting another zoned date and time from this one, resulting in the elapsed duration
between the two instants represented in the values.
Since 2.0.x
Availability net45, netstandard1.3
Declaration
public Duration Minus(ZonedDateTime other)Parameters
| Type | Name | Description |
|---|---|---|
| ZonedDateTime | other | The zoned date and time to subtract from this one. |
Returns
| Type | Description |
|---|---|
| Duration | The elapsed duration from other to this value. |
Remarks
This is an alternative way of calling Subtraction(ZonedDateTime, ZonedDateTime).
Sample snippet
using NodaTime;
using System;
var zone = DateTimeZone.ForOffset(Offset.FromHours(-5));
ZonedDateTime subject = new ZonedDateTime(Instant.FromUtc(2017, 7, 17, 7, 17), zone);
ZonedDateTime other = new ZonedDateTime(Instant.FromUtc(2017, 7, 17, 9, 17), zone);
var difference = other.Minus(subject);
Console.WriteLine(difference);
Output:
0:02:00:00
Plus(Duration)
Returns the result of adding a duration to this zoned date and time.
Since 1.0.x
Availability net45, netstandard1.3
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. |
Remarks
This is an alternative way of calling Addition(ZonedDateTime, Duration).
Sample snippet
using NodaTime;
using System;
// Europe/Dublin transitions from UTC+1 to UTC+0 at 2am (local) on 2017-10-29
var dt = new LocalDateTime(2017, 10, 29, 1, 45, 0);
DateTimeZone dublin = DateTimeZoneProviders.Tzdb["Europe/Dublin"];
ZonedDateTime beforeTransition = new ZonedDateTime(dt, dublin, Offset.FromHours(1));
var result = ZonedDateTime.Add(beforeTransition, Duration.FromHours(1));
Console.WriteLine(result.Date);
// Adding an hour of elapsed time takes us across the DST transition, so we have
// the same local time (shown on a clock) but a different offset.
Console.WriteLine(result);
// The + operator and Plus instance method are equivalent to the Add static method.
var result2 = beforeTransition + Duration.FromHours(1);
var result3 = beforeTransition.Plus(Duration.FromHours(1));
Console.WriteLine(result2);
Console.WriteLine(result3);
Output:
Sunday, 29 October 2017
2017-10-29T01:45:00 Europe/Dublin (+00)
2017-10-29T01:45:00 Europe/Dublin (+00)
2017-10-29T01:45:00 Europe/Dublin (+00)
PlusHours(Int32)
Returns the result of adding a increment of hours to this zoned date and time
Since 2.0.x
Availability net45, netstandard1.3
Declaration
public ZonedDateTime PlusHours(int hours)Parameters
| Type | Name | Description |
|---|---|---|
| Int32 | hours | The number of hours to add |
Returns
| Type | Description |
|---|---|
| ZonedDateTime | A new ZonedDateTime representing the result of the addition. |
Sample snippet
using NodaTime;
using NodaTime.Text;
using System;
DateTimeZone dublin = DateTimeZoneProviders.Tzdb["Europe/Dublin"];
var start = Instant.FromUtc(2017, 7, 20, 5, 30);
// Dublin is at UTC+1 in July 2017, so this is 6:30am.
ZonedDateTime zoned = new ZonedDateTime(start, dublin);
var pattern = ZonedDateTimePattern.ExtendedFormatOnlyIso;
Console.WriteLine( pattern.Format(zoned.PlusHours(1)));
Output:
2017-07-20T07:30:00 Europe/Dublin (+01)
PlusMilliseconds(Int64)
Returns the result of adding an increment of milliseconds to this zoned date and time
Since 2.0.x
Availability net45, netstandard1.3
Declaration
public ZonedDateTime PlusMilliseconds(long milliseconds)Parameters
| Type | Name | Description |
|---|---|---|
| Int64 | milliseconds | The number of milliseconds to add |
Returns
| Type | Description |
|---|---|
| ZonedDateTime | A new ZonedDateTime representing the result of the addition. |
Sample snippet
using NodaTime;
using NodaTime.Text;
using System;
DateTimeZone dublin = DateTimeZoneProviders.Tzdb["Europe/Dublin"];
var start = Instant.FromUtc(2017, 7, 20, 5, 30);
// Dublin is at UTC+1 in July 2017, so this is 6:30am.
ZonedDateTime zoned = new ZonedDateTime(start, dublin);
var pattern = ZonedDateTimePattern.ExtendedFormatOnlyIso;
Console.WriteLine( pattern.Format(zoned.PlusMilliseconds(1)));
Output:
2017-07-20T06:30:00.001 Europe/Dublin (+01)
PlusMinutes(Int32)
Returns the result of adding an increment of minutes to this zoned date and time
Since 2.0.x
Availability net45, netstandard1.3
Declaration
public ZonedDateTime PlusMinutes(int minutes)Parameters
| Type | Name | Description |
|---|---|---|
| Int32 | minutes | The number of minutes to add |
Returns
| Type | Description |
|---|---|
| ZonedDateTime | A new ZonedDateTime representing the result of the addition. |
Sample snippet
using NodaTime;
using NodaTime.Text;
using System;
DateTimeZone dublin = DateTimeZoneProviders.Tzdb["Europe/Dublin"];
var start = Instant.FromUtc(2017, 7, 20, 5, 30);
// Dublin is at UTC+1 in July 2017, so this is 6:30am.
ZonedDateTime zoned = new ZonedDateTime(start, dublin);
var pattern = ZonedDateTimePattern.ExtendedFormatOnlyIso;
Console.WriteLine( pattern.Format(zoned.PlusMinutes(1)));
Output:
2017-07-20T06:31:00 Europe/Dublin (+01)
PlusNanoseconds(Int64)
Returns the result of adding an increment of nanoseconds to this zoned date and time
Since 2.0.x
Availability net45, netstandard1.3
Declaration
public ZonedDateTime PlusNanoseconds(long nanoseconds)Parameters
| Type | Name | Description |
|---|---|---|
| Int64 | nanoseconds | The number of nanoseconds to add |
Returns
| Type | Description |
|---|---|
| ZonedDateTime | A new ZonedDateTime representing the result of the addition. |
Sample snippet
using NodaTime;
using NodaTime.Text;
using System;
DateTimeZone dublin = DateTimeZoneProviders.Tzdb["Europe/Dublin"];
var start = Instant.FromUtc(2017, 7, 20, 5, 30);
// Dublin is at UTC+1 in July 2017, so this is 6:30am.
ZonedDateTime zoned = new ZonedDateTime(start, dublin);
var pattern = ZonedDateTimePattern.ExtendedFormatOnlyIso;
Console.WriteLine( pattern.Format(zoned.PlusNanoseconds(1)));
Output:
2017-07-20T06:30:00.000000001 Europe/Dublin (+01)
PlusSeconds(Int64)
Returns the result of adding an increment of seconds to this zoned date and time
Since 2.0.x
Availability net45, netstandard1.3
Declaration
public ZonedDateTime PlusSeconds(long seconds)Parameters
| Type | Name | Description |
|---|---|---|
| Int64 | seconds | The number of seconds to add |
Returns
| Type | Description |
|---|---|
| ZonedDateTime | A new ZonedDateTime representing the result of the addition. |
Sample snippet
using NodaTime;
using NodaTime.Text;
using System;
DateTimeZone dublin = DateTimeZoneProviders.Tzdb["Europe/Dublin"];
var start = Instant.FromUtc(2017, 7, 20, 5, 30);
// Dublin is at UTC+1 in July 2017, so this is 6:30am.
ZonedDateTime zoned = new ZonedDateTime(start, dublin);
var pattern = ZonedDateTimePattern.ExtendedFormatOnlyIso;
Console.WriteLine( pattern.Format(zoned.PlusSeconds(1)));
Output:
2017-07-20T06:30:01 Europe/Dublin (+01)
PlusTicks(Int64)
Returns the result of adding an increment of ticks to this zoned date and time
Since 2.0.x
Availability net45, netstandard1.3
Declaration
public ZonedDateTime PlusTicks(long ticks)Parameters
| Type | Name | Description |
|---|---|---|
| Int64 | ticks | The number of ticks to add |
Returns
| Type | Description |
|---|---|
| ZonedDateTime | A new ZonedDateTime representing the result of the addition. |
Sample snippet
using NodaTime;
using NodaTime.Text;
using System;
DateTimeZone dublin = DateTimeZoneProviders.Tzdb["Europe/Dublin"];
var start = Instant.FromUtc(2017, 7, 20, 5, 30);
// Dublin is at UTC+1 in July 2017, so this is 6:30am.
ZonedDateTime zoned = new ZonedDateTime(start, dublin);
var pattern = ZonedDateTimePattern.ExtendedFormatOnlyIso;
Console.WriteLine( pattern.Format(zoned.PlusTicks(1)));
Output:
2017-07-20T06:30:00.0000001 Europe/Dublin (+01)
Subtract(ZonedDateTime, Duration)
Subtracts a duration from a zoned date and time.
Since 1.0.x
Availability net45, netstandard1.3
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. |
Remarks
This is an alternative way of calling Subtraction(ZonedDateTime, Duration).
Sample snippet
using NodaTime;
using System;
// Europe/Dublin transitions from UTC+1 to UTC+0 at 2am (local) on 2017-10-29
var dt = new LocalDateTime(2017, 10, 29, 1, 45, 0);
DateTimeZone dublin = DateTimeZoneProviders.Tzdb["Europe/Dublin"];
ZonedDateTime afterTransition = new ZonedDateTime(dt, dublin, Offset.FromHours(0));
var result = ZonedDateTime.Subtract(afterTransition, Duration.FromHours(1));
Console.WriteLine(result.Date);
// Adding an hour of elapsed time takes us across the DST transition, so we have
// the same local time (shown on a clock) but a different offset.
Console.WriteLine(result);
// The + operator and Plus instance method are equivalent to the Add static method.
var result2 = afterTransition - Duration.FromHours(1);
var result3 = afterTransition.Minus(Duration.FromHours(1));
Console.WriteLine(result2);
Console.WriteLine(result3);
Output:
Sunday, 29 October 2017
2017-10-29T01:45:00 Europe/Dublin (+01)
2017-10-29T01:45:00 Europe/Dublin (+01)
2017-10-29T01:45:00 Europe/Dublin (+01)
Subtract(ZonedDateTime, ZonedDateTime)
Subtracts one zoned date and time from another, returning an elapsed duration.
Since 2.0.x
Availability net45, netstandard1.3
Declaration
public static Duration Subtract(ZonedDateTime end, ZonedDateTime start)Parameters
| Type | Name | Description |
|---|---|---|
| ZonedDateTime | end | The zoned date and time value to subtract from; if this is later than start
then the result will be positive. |
| ZonedDateTime | start | The zoned date and time to subtract from end. |
Returns
| Type | Description |
|---|---|
| Duration | The elapsed duration from start to end. |
Remarks
This is an alternative way of calling Subtraction(ZonedDateTime, ZonedDateTime).
Sample snippet
using NodaTime;
using System;
var zone = DateTimeZone.ForOffset(Offset.FromHours(-5));
ZonedDateTime subject = new ZonedDateTime(Instant.FromUtc(2017, 7, 17, 7, 17), zone);
ZonedDateTime other = new ZonedDateTime(Instant.FromUtc(2017, 7, 17, 9, 17), zone);
var difference = ZonedDateTime.Subtract(other, subject);
Console.WriteLine(difference);
Output:
0:02:00:00
ToDateTimeOffset()
Constructs a System.DateTimeOffset value with the same local time and offset from
UTC as this value.
Since 1.0.x
Availability net45, netstandard1.3
Declaration
public DateTimeOffset ToDateTimeOffset()Returns
| Type | Description |
|---|---|
| DateTimeOffset | A DateTimeOffset with the same local date/time and offset as this. The System.DateTime part of
the result always has a "kind" of Unspecified. |
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.
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.
If the offset has a non-zero second component, this is truncated as DateTimeOffset has an offset
granularity of minutes.
Exceptions
| Type | Condition |
|---|---|
| System.InvalidOperationException | The date/time is outside the range of DateTimeOffset,
or the offset is outside the range of +/-14 hours (the range supported by DateTimeOffset). |
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 net45, netstandard1.3
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.
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.
Exceptions
| Type | Condition |
|---|---|
| System.InvalidOperationException | The date/time is outside the range of DateTime. |
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 net45, netstandard1.3
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. |
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.
Exceptions
| Type | Condition |
|---|---|
| System.InvalidOperationException | The final date/time is outside the range of DateTime. |
ToInstant()
Converts this value to the instant it represents on the time line.
Since 1.0.x
Availability net45, netstandard1.3
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 net45, netstandard1.3
Declaration
public OffsetDateTime ToOffsetDateTime()Returns
| Type | Description |
|---|---|
| OffsetDateTime | An OffsetDateTime with the same local date/time and offset as this value. |
ToString()
Returns a System.String that represents this instance.
Since 1.0.x
Availability net45, netstandard1.3
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.2.x
Availability net45, netstandard1.3
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. |
WithCalendar(CalendarSystem)
Creates a new ZonedDateTime representing the same physical date, time and offset, but in a different calendar.
The returned ZonedDateTime is likely to have different date field values to this one.
For example, January 1st 1970 in the Gregorian calendar was December 19th 1969 in the Julian calendar.
Since 2.0.x
Availability net45, netstandard1.3
Declaration
public ZonedDateTime WithCalendar(CalendarSystem calendar)Parameters
| Type | Name | Description |
|---|---|---|
| CalendarSystem | calendar | The calendar system to convert this zoned date and time to. |
Returns
| Type | Description |
|---|---|
| ZonedDateTime | The converted ZonedDateTime. |
Exceptions
| Type | Condition |
|---|---|
| ArgumentNullException | calendar is null. |
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 net45, netstandard1.3
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 |
|---|---|
| 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 net45, netstandard1.3
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
zonedDateTime.
Sample snippet
using NodaTime;
using System;
// Europe/Dublin transitions from UTC+1 to UTC+0 at 2am (local) on 2017-10-29
var dt = new LocalDateTime(2017, 10, 29, 1, 45, 0);
DateTimeZone dublin = DateTimeZoneProviders.Tzdb["Europe/Dublin"];
ZonedDateTime beforeTransition = new ZonedDateTime(dt, dublin, Offset.FromHours(1));
var result = ZonedDateTime.Add(beforeTransition, Duration.FromHours(1));
Console.WriteLine(result.Date);
// Adding an hour of elapsed time takes us across the DST transition, so we have
// the same local time (shown on a clock) but a different offset.
Console.WriteLine(result);
// The + operator and Plus instance method are equivalent to the Add static method.
var result2 = beforeTransition + Duration.FromHours(1);
var result3 = beforeTransition.Plus(Duration.FromHours(1));
Console.WriteLine(result2);
Console.WriteLine(result3);
Output:
Sunday, 29 October 2017
2017-10-29T01:45:00 Europe/Dublin (+00)
2017-10-29T01:45:00 Europe/Dublin (+00)
2017-10-29T01:45:00 Europe/Dublin (+00)
Equality(ZonedDateTime, ZonedDateTime)
Implements the operator ==.
Since 1.0.x
Availability net45, netstandard1.3
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 |
Inequality(ZonedDateTime, ZonedDateTime)
Implements the operator !=.
Since 1.0.x
Availability net45, netstandard1.3
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 |
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 net45, netstandard1.3
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
zonedDateTime.
Sample snippet
using NodaTime;
using System;
// Europe/Dublin transitions from UTC+1 to UTC+0 at 2am (local) on 2017-10-29
var dt = new LocalDateTime(2017, 10, 29, 1, 45, 0);
DateTimeZone dublin = DateTimeZoneProviders.Tzdb["Europe/Dublin"];
ZonedDateTime afterTransition = new ZonedDateTime(dt, dublin, Offset.FromHours(0));
var result = ZonedDateTime.Subtract(afterTransition, Duration.FromHours(1));
Console.WriteLine(result.Date);
// Adding an hour of elapsed time takes us across the DST transition, so we have
// the same local time (shown on a clock) but a different offset.
Console.WriteLine(result);
// The + operator and Plus instance method are equivalent to the Add static method.
var result2 = afterTransition - Duration.FromHours(1);
var result3 = afterTransition.Minus(Duration.FromHours(1));
Console.WriteLine(result2);
Console.WriteLine(result3);
Output:
Sunday, 29 October 2017
2017-10-29T01:45:00 Europe/Dublin (+01)
2017-10-29T01:45:00 Europe/Dublin (+01)
2017-10-29T01:45:00 Europe/Dublin (+01)
Subtraction(ZonedDateTime, ZonedDateTime)
Subtracts one ZonedDateTime from another, resulting in the elapsed time between
the two values.
Since 2.0.x
Availability net45, netstandard1.3
Declaration
public static Duration operator -(ZonedDateTime end, ZonedDateTime start)Parameters
| Type | Name | Description |
|---|---|---|
| ZonedDateTime | end | The zoned date and time value to subtract from; if this is later than start
then the result will be positive. |
| ZonedDateTime | start | The zoned date and time to subtract from end. |
Returns
| Type | Description |
|---|---|
| Duration | The elapsed duration from start to end. |
Remarks
This is equivalent to
end.ToInstant() - start.ToInstant(); in particular:
- The two values can use different calendar systems
- The two values can be in different time zones
- The two values can have different UTC offsets
Explicit Interface Implementations
ISerializable.GetObjectData(SerializationInfo, StreamingContext)
Implementation of System.Runtime.Serialization.ISerializable.GetObjectData(System.Runtime.Serialization.SerializationInfo, System.Runtime.Serialization.StreamingContext).
Since 1.2.x
Availability net45
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 net45, netstandard1.3
Declaration
XmlSchema IXmlSerializable.GetSchema()Returns
| Type | Description |
|---|---|
| XmlSchema |
IXmlSerializable.ReadXml(XmlReader)
Since 1.2.x
Availability net45, netstandard1.3
Declaration
void IXmlSerializable.ReadXml(XmlReader reader)Parameters
| Type | Name | Description |
|---|---|---|
| XmlReader | reader |
Exceptions
| Type | Condition |
|---|---|
| ArgumentNullException | reader is null. |
IXmlSerializable.WriteXml(XmlWriter)
Since 1.2.x
Availability net45, netstandard1.3
Declaration
void IXmlSerializable.WriteXml(XmlWriter writer)Parameters
| Type | Name | Description |
|---|---|---|
| XmlWriter | writer |
Exceptions
| Type | Condition |
|---|---|
| ArgumentNullException | writer is null. |
Implements
System.IEquatable<T>
System.IFormattable
System.Xml.Serialization.IXmlSerializable
System.Runtime.Serialization.ISerializable