Conversions

Converting Date/Time without time zone information

To convert from a ZonedDateTime into a vanilla DateTime, one can use the DateTime constructor. Passing either Local to directly drop the time zone, or UTC to extract the time as UTC instead. The canonical way to represent datetimes is generally in UTC, as this is a requirement to correctly compute the Unix Timestamp.

julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"UTC-4")
2014-05-30T21:00:00-04:00

julia> DateTime(zdt, Local)
2014-05-30T21:00:00

julia> DateTime(zdt, UTC)
2014-05-31T01:00:00

Similar can be done for Date and Time:

julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"UTC-4")
2014-05-30T21:00:00-04:00

julia> Date(zdt, Local)
2014-05-30

julia> Date(zdt, UTC)
2014-05-31

julia> Time(zdt, Local)
21:00:00
julia> Time(zdt, UTC)
01:00:00

Switching Time Zones

Switching an existing ZonedDateTime from one TimeZone to another can be done with the function astimezone:

julia> zdt = ZonedDateTime(2014, 1, 1, tz"UTC")
2014-01-01T00:00:00+00:00

julia> astimezone(zdt, tz"Asia/Tokyo")
2014-01-01T09:00:00+09:00

Parsing strings

ZonedDateTime parsing extends the functionality provided by Dates. If you haven't already it is recommended that you first read the official Julia manual on Date and DateTime. The TimeZones package adds z and Z to the list of available parsing character codes:

Note that with the exception of "UTC" and "GMT" time zone abbrevations cannot be parsed using the Z character code since most abbreviations are ambiguous. For example abbreviation "MST" could be interpreted as "Mountain Standard Time" (UTC-7) or "Moscow Summer Time" (UTC+3:31).

Parsing a ZonedDateTime just requires the text to parse and a format string:

julia> ZonedDateTime("20150101-0700", "yyyymmddzzzz")
2015-01-01T00:00:00-07:00

julia> ZonedDateTime("2015-08-06T22:25:31+07:00", "yyyy-mm-ddTHH:MM:SSzzzz")
2015-08-06T22:25:31+07:00

When parsing several ZonedDateTime strings which use the same format you will see better performance if you first create a Dates.DateFormat instead of passing in a raw format string.

julia> df = Dates.DateFormat("yy-mm-ddz");

julia> ZonedDateTime("2015-03-29+01:00", df)
2015-03-29T00:00:00+01:00

julia> ZonedDateTime("2015-03-30+02:00", df)
2015-03-30T00:00:00+02:00

Formatting strings

Formatting a ZonedDateTime as a string also extends the functionality provided by Base.Dates. The TimeZones package adds the new formatting character codes z and Z to the list of available formatting character codes:

It is recommended that you prefer the use of the z character code over Z time zone abbreviations can be interpreted in different ways.

Formatting uses the Dates.format function with a ZonedDateTime and a format string:

julia> zdt = ZonedDateTime(2015, 8, 6, 22, 25, tz"Europe/Warsaw")
2015-08-06T22:25:00+02:00

julia> Dates.format(zdt, "yyyymmddzzzz")
"20150806+02:00"

julia> Dates.format(zdt, "yyyy-mm-dd HH:MM ZZZ")
"2015-08-06 22:25 CEST"