Converting

Conversions

Converting Date/Time without time zone information

To convert from a ZonedDateTime into a vanilla DateTime, one can use the DateTime constructor. Just passing in the ZonedDateTime will directly drop the time zone, and passing in UTC as the second argument will extract the time as UTC instead. Note: 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)
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)
2014-05-30

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

julia> Time(zdt)
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:

CodeMatchesComment
z+04:00, +0400, UTC+4Matches a numeric UTC offset
ZAsia/Dubai, UTCMatches names of time zones from the TZ database

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:

CodeExamplesComment
z+04:00Numeric UTC offset
ZGST, UTCTime zone abbreviation

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"