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 net6.0, netstandard2.0

Implements

IEquatable<ZonedDateTime>

IFormattable

IXmlSerializable

Inherited Members

Object.Equals(Object, Object)

Object.GetType()

Object.ReferenceEquals(Object, Object)

Namespace: NodaTime

Assembly: NodaTime.dll

Syntax

[TypeConverter(typeof(ZonedDateTimeTypeConverter))]
public readonly struct ZonedDateTime : IEquatable<ZonedDateTime>, IFormattable, IXmlSerializable

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.

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 net6.0, netstandard2.0

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 net6.0, netstandard2.0

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.

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 net6.0, netstandard2.0

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.

Properties

Calendar

Gets the calendar system associated with this zoned date and time.

Since 1.2.x

Availability net6.0, netstandard2.0

Declaration

public readonly CalendarSystem Calendar { get; }

Property Value

Type	Description
CalendarSystem	The calendar system associated with this zoned date and time.

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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly Era Era { get; }

Property Value

Type	Description
Era	The era for this zoned date and time.

Hour

Gets the hour of day of this zoned date and time, in the range 0 to 23 inclusive.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly DateTimeZone Zone { get; }

Property Value

Type	Description
DateTimeZone	The time zone associated with this value.

Methods

Add(ZonedDateTime, Duration)

Adds a duration to a zoned date and time.

Since 1.0.x

Availability net6.0, netstandard2.0

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)

AddSchema(XmlSchemaSet)

Adds the XML schema type describing the structure of the ZonedDateTime XML serialization to the given xmlSchemaSet.

Since 3.0.x

Availability net6.0, netstandard2.0

Declaration

public static XmlQualifiedName AddSchema(XmlSchemaSet xmlSchemaSet)

Parameters

Type	Name	Description
XmlSchemaSet	xmlSchemaSet	The XML schema set provided by System.Xml.Serialization.XmlSchemaExporter.

Returns

Type	Description
XmlQualifiedName	The qualified name of the schema type that was added to the xmlSchemaSet.

Deconstruct(out LocalDateTime, out DateTimeZone, out Offset)

Deconstruct this ZonedDateTime into its components.

Since 2.3.x

Availability net6.0, netstandard2.0

Declaration

public readonly 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. See the type documentation for a description of equality semantics.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public readonly 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. See the type documentation for a description of equality semantics.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public override readonly 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 net6.0, netstandard2.0

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. See the type documentation for a description of equality semantics.

Since 1.0.x

Availability net6.0, netstandard2.0

Declaration

public override readonly 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 net6.0, netstandard2.0

Declaration

public readonly ZoneInterval GetZoneInterval()

Returns

Type	Description
ZoneInterval	The ZoneInterval containing this value.

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 net6.0, netstandard2.0

Declaration

public readonly 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
// However, Europe/Dublin is also odd in terms of having its standard time as *summer* time,
// and its winter time as "daylight saving time". The saving offset in winter is -1 hour,
// as opposed to the more common "+1 hour in summer".
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

GetZoneInterval()

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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

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 net6.0, netstandard2.0

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 net6.0, netstandard2.0

Declaration

public readonly 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.

System.DateTimeOffset uses the Gregorian calendar by definition, so the value is implicitly converted to the Gregorian calendar first. The result will be the same instant in time (potentially truncated as described above), but the values returned by the Year/Month/Day properties of the System.DateTimeOffset may not match the Year/Month/Day properties of this value.

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 net6.0, netstandard2.0

Declaration

public readonly 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.

System.DateTime uses the Gregorian calendar by definition, so the value is implicitly converted to the Gregorian calendar first. The result will be on the same physical date, but the values returned by the Year/Month/Day properties of the System.DateTime may not match the Year/Month/Day properties of this value.

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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public override readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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 net6.0, netstandard2.0

Declaration

public readonly 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.

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 net6.0, netstandard2.0

Declaration

public readonly 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.

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 net6.0, netstandard2.0

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 ==. See the type documentation for a description of equality semantics.

Since 1.0.x

Availability net6.0, netstandard2.0

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 !=. See the type documentation for a description of equality semantics.

Since 1.0.x

Availability net6.0, netstandard2.0

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 net6.0, netstandard2.0

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 net6.0, netstandard2.0

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

IXmlSerializable.ReadXml(XmlReader)

Since 1.2.x

Availability net6.0, netstandard2.0

Declaration

readonly void IXmlSerializable.ReadXml(XmlReader reader)

Parameters

Type	Name	Description
XmlReader	reader

IXmlSerializable.WriteXml(XmlWriter)

Since 1.2.x

Availability net6.0, netstandard2.0

Declaration

readonly void IXmlSerializable.WriteXml(XmlWriter writer)

Parameters

Type	Name	Description
XmlWriter	writer

Implements

System.IEquatable<T>

System.IFormattable

System.Xml.Serialization.IXmlSerializable