TimeZones Public API

TimeZone(str::AbstractString) -> TimeZone

Constructs a TimeZone subtype based upon the string. If the string is a recognized standard time zone name then data is loaded from the compiled IANA time zone database. Otherwise the string is parsed as a fixed time zone.

A list of recognized standard and legacy time zones names can is available by running timezone_names(). Supported fixed time zone string formats can be found in docstring for FixedTimeZone(::AbstractString).

Examples

julia> TimeZone("Europe/Warsaw")
Europe/Warsaw (UTC+1/UTC+2)

julia> TimeZone("UTC")
UTC

@tz_str -> TimeZone

Constructs a TimeZone subtype based upon the string at parse time. See docstring of TimeZone for more details.

julia> tz"Africa/Nairobi"
Africa/Nairobi (UTC+3)

localzone() -> TimeZone

Returns a TimeZone object that is equivalent to the system's current time zone.

FixedTimeZone

A TimeZone with a constant offset for all of time.

VariableTimeZone

A TimeZone with an offset that changes over time.

build(version::AbstractString; force::Bool=false) -> Nothing

Builds the TimeZones package with the specified tzdata version and regions. The version is typically a 4-digit year followed by a lowercase ASCII letter (e.g. "2024b"). The force flag is used to re-download tzdata archives.

TimeZone(str::AbstractString, mask::Class) -> TimeZone

Similar to TimeZone(::AbstractString) but allows you to control what time zone classes are allowed to be constructed with mask. Can be used to construct time zones which are classified as "legacy".

Examples

julia> TimeZone("US/Pacific")
ERROR: ArgumentError: The time zone "US/Pacific" is of class `TimeZones.Class(:LEGACY)` which is currently not allowed by the mask: `TimeZones.Class(:FIXED) | TimeZones.Class(:STANDARD)`

julia> TimeZone("US/Pacific", TimeZones.Class(:LEGACY))
US/Pacific (UTC-8/UTC-7)

Class

A type used for controlling which classes of TimeZone are considered valid. Instances of Class can be combined using bitwise operators to generate a mask which allows multiple classes to be considered valid at once.

Currently supported masks are:

• Class(:FIXED): Class indicating the time zone name is parsable as a fixed UTC offset.
• Class(:STANDARD): The time zone name is included in the primary IANA tz source files.
• Class(:LEGACY): The time zone name is included in the deprecated IANA tz source files.
• Class(:NONE): Mask that will match nothing.
• Class(:DEFAULT): Default mask used by functions: Class(:FIXED) | Class(:STANDARD)
• Class(:ALL): Mask allowing all supported classes.

istimezone(str::AbstractString, mask::Class=Class(:DEFAULT)) -> Bool

Check whether a string is a valid for constructing a TimeZone with the provided mask.

ZonedDateTime(y, [m, d, h, mi, s, ms], tz, [amb]) -> ZonedDateTime

Construct a ZonedDateTime type by parts. Arguments y, m, ..., ms must be convertible to Int64 and tz must be a TimeZone. If the given provided local time is ambiguous in the given TimeZone then amb can be supplied to resolve ambiguity.

ZonedDateTime(dt::DateTime, tz::TimeZone; from_utc=false) -> ZonedDateTime

Construct a ZonedDateTime by applying a TimeZone to a DateTime. When the from_utc keyword is true the given DateTime is assumed to be in UTC instead of in local time and is converted to the specified TimeZone. Note that when from_utc is true the given DateTime will always exists and is never ambiguous.

ZonedDateTime(dt::DateTime, tz::VariableTimeZone, occurrence::Integer) -> ZonedDateTime

Construct a ZonedDateTime by applying a TimeZone to a DateTime. If the DateTime is ambiguous within the given time zone you can set occurrence to a positive integer to resolve the ambiguity.

ZonedDateTime(dt::DateTime, tz::VariableTimeZone, is_dst::Bool) -> ZonedDateTime

Construct a ZonedDateTime by applying a TimeZone to a DateTime. If the DateTime is ambiguous within the given time zone you can set is_dst to resolve the ambiguity.

ZonedDateTime(date::Date, ...)
ZonedDateTime(date::Date, time::Time, ...)

Construct a ZonedDateTime from Date and Time arguments.

astimezone(zdt::ZonedDateTime, tz::TimeZone) -> ZonedDateTime

Converts a ZonedDateTime from its current TimeZone into the specified TimeZone.

timezone(::ZonedDateTime) -> TimeZone

Returns the TimeZone used by the ZonedDateTime.

TimeZone(zdt::ZonedDateTime) -> TimeZone

Extract the TimeZone associated with the ZonedDateTime.

See also: timezone(::ZonedDateTime), FixedTimeZone(::ZonedDateTime).

Examples

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

julia> TimeZone(zdt)
America/New_York (UTC-5/UTC-4)

FixedTimeZone(zdt::ZonedDateTime) -> FixedTimeZone

Construct a FixedTimeZone using the UTC offset for the timestamp provided by the ZonedDateTime. If the timezone used by the ZonedDateTime has UTC offsets that change over time the returned FixedTimeZone will vary based upon the timestamp.

See also: TimeZone(::ZonedDateTime).

Example

julia> zdt1 = ZonedDateTime(2014, 5, 30, 21, tz"America/New_York")
2014-05-30T21:00:00-04:00

julia> FixedTimeZone(zdt1)
EDT (UTC-4)

julia> zdt2 = ZonedDateTime(2014, 2, 18, 6, tz"America/New_York")
2014-02-18T06:00:00-05:00

julia> FixedTimeZone(zdt2)
EST (UTC-5)

DateTime(zdt::ZonedDateTime) -> DateTime

Construct a DateTime based on the "local time" representation of the provided ZonedDateTime.

See also: DateTime(::ZonedDateTime, ::Type{UTC}).

Example

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

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

DateTime(zdt::ZonedDateTime, ::Type{UTC}) -> DateTime

Construct a DateTime based on the UTC representation of the provided ZonedDateTime.

See also: DateTime(::ZonedDateTime).

Example

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

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

Date(zdt::ZonedDateTime) -> Date

Construct a Date based on the "local time" representation of the provided ZonedDateTime.

See also: Date(::ZonedDateTime, ::Type{UTC}).

Example

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

julia> Date(zdt)
2014-05-30

Date(zdt::ZonedDateTime, ::Type{UTC}) -> Date

Construct a Date based on the UTC representation of the provided ZonedDateTime.

See also: Date(::ZonedDateTime).

Example

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

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

Time(zdt::ZonedDateTime) -> Time

Construct a Time based on the "local time" representation of the provided ZonedDateTime.

See also: Time(::ZonedDateTime, ::Type{UTC}).

Example

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

julia> Time(zdt)
21:00:00

Time(zdt::ZonedDateTime, ::Type{UTC}) -> Date

Construct a Time based on the UTC representation of the provided ZonedDateTime.

See also: Time(::ZonedDateTime).

Example

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

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

now(::TimeZone) -> ZonedDateTime

Create a ZonedDateTime corresponding to the current system time in the specified TimeZone.

See also: today(::TimeZone), todayat(::TimeZone).

today(tz::TimeZone) -> Date

Create the current Date in the specified TimeZone. Equivalent to Date(now(tz)).

See also: now(::TimeZone), todayat(::TimeZone).

Examples

julia> a, b = now(tz"Pacific/Midway"), now(tz"Pacific/Apia")
(2017-11-09T03:47:04.226-11:00, 2017-11-10T04:47:04.226+14:00)

julia> a - b
0 milliseconds

julia> today(tz"Pacific/Midway"), today(tz"Pacific/Apia")
(2017-11-09, 2017-11-10)

todayat(tod::Time, tz::TimeZone, [amb::Union{Integer,Bool}]) -> ZonedDateTime

Creates a ZonedDateTime for today at the specified time of day. If the result is ambiguous in the given TimeZone then amb can be supplied to resolve ambiguity.

See also: now(::TimeZone), today(::TimeZone).

Examples

julia> today(tz"Europe/Warsaw")
2017-10-29

julia> todayat(Time(10, 30), tz"Europe/Warsaw")
2017-10-29T10:30:00+01:00

julia> todayat(Time(2), tz"Europe/Warsaw")
ERROR: AmbiguousTimeError: Local DateTime 2017-10-29T02:00:00 is ambiguous within Europe/Warsaw

julia> todayat(Time(2), tz"Europe/Warsaw", 1)
2017-10-29T02:00:00+02:00

julia> todayat(Time(2), tz"Europe/Warsaw", 2)
2017-10-29T02:00:00+01:00

round(zdt::ZonedDateTime, p::Period, [r::RoundingMode]) -> ZonedDateTime
round(zdt::ZonedDateTime, p::Type{Period}, [r::RoundingMode]) -> ZonedDateTime

Returns the ZonedDateTime nearest to zdt at resolution p. The result will be in the same time zone as zdt. By default (RoundNearestTiesUp), ties (e.g., rounding 9:30 to the nearest hour) will be rounded up.

For convenience, p may be a type instead of a value: round(zdt, Dates.Hour) is a shortcut for round(zdt, Dates.Hour(1)).

Valid rounding modes for round(::TimeType, ::Period, ::RoundingMode) are RoundNearestTiesUp (default), RoundDown (floor), and RoundUp (ceil).

VariableTimeZone Transitions

Instead of performing rounding operations on the ZonedDateTime's internal UTC DateTime, which would be computationally less expensive, rounding is done in the local time zone. This ensures that rounding behaves as expected and is maximally meaningful.

If rounding were done in UTC, consider how rounding to the nearest day would be resolved for non-UTC time zones: the result would be 00:00 UTC, which wouldn't be midnight local time. Similarly, when rounding to the nearest hour in Australia/Eucla (UTC+08:45), the result wouldn't be on the hour in the local time zone.

When p is a DatePeriod rounding is done in the local time zone in a straightforward fashion. When p is a TimePeriod the likelihood of encountering an ambiguous or non-existent time (due to daylight saving time transitions) is increased. To resolve this issue, rounding a ZonedDateTime with a VariableTimeZone to a TimePeriod uses the DateTime value in the appropriate FixedTimeZone, then reconverts it to a ZonedDateTime in the appropriate VariableTimeZone afterward.

Rounding is not an entirely "safe" operation for ZonedDateTimes, as in some cases historical transitions for some time zones (such as Asia/Colombo) occur at midnight. In such cases rounding to a DatePeriod may still result in an AmbiguousTimeError or a NonExistentTimeError. (But these events should be relatively rare.)

Regular daylight saving time transitions should be safe.

Examples

The America/Winnipeg time zone transitioned from Central Standard Time (UTC-6:00) to Central Daylight Time (UTC-5:00) on 2016-03-13, moving directly from 01:59:59 to 03:00:00.

julia> zdt = ZonedDateTime(2016, 3, 13, 1, 45, TimeZone("America/Winnipeg"))
2016-03-13T01:45:00-06:00

julia> round(zdt, Dates.Hour)
2016-03-13T03:00:00-05:00

julia> round(zdt, Dates.Day)
2016-03-13T00:00:00-06:00

The Asia/Colombo time zone revised the definition of Lanka Time from UTC+6:30 to UTC+6:00 on 1996-10-26, moving from 00:29:59 back to 00:00:00.

julia> zdt = ZonedDateTime(1996, 10, 25, 23, 45, TimeZone("Asia/Colombo"))
1996-10-25T23:45:00+06:30

julia> round(zdt, Dates.Hour)
1996-10-26T00:00:00+06:30

julia> round(zdt, Dates.Day)
ERROR: Local DateTime 1996-10-26T00:00:00 is ambiguous

floor(zdt::ZonedDateTime, p::Period) -> ZonedDateTime
floor(zdt::ZonedDateTime, p::Type{Period}) -> ZonedDateTime

Returns the nearest ZonedDateTime less than or equal to zdt at resolution p. The result will be in the same time zone as zdt.

For convenience, p may be a type instead of a value: floor(zdt, Dates.Hour) is a shortcut for floor(zdt, Dates.Hour(1)).

VariableTimeZone transitions are handled as for round.

Examples

The America/Winnipeg time zone transitioned from Central Standard Time (UTC-6:00) to Central Daylight Time (UTC-5:00) on 2016-03-13, moving directly from 01:59:59 to 03:00:00.

julia> zdt = ZonedDateTime(2016, 3, 13, 1, 45, TimeZone("America/Winnipeg"))
2016-03-13T01:45:00-06:00

julia> floor(zdt, Dates.Day)
2016-03-13T00:00:00-06:00

julia> floor(zdt, Dates.Hour)
2016-03-13T01:00:00-06:00

ceil(zdt::ZonedDateTime, p::Period) -> ZonedDateTime
ceil(zdt::ZonedDateTime, p::Type{Period}) -> ZonedDateTime

Returns the nearest ZonedDateTime greater than or equal to zdt at resolution p. The result will be in the same time zone as zdt.

For convenience, p may be a type instead of a value: ceil(zdt, Dates.Hour) is a shortcut for ceil(zdt, Dates.Hour(1)).

VariableTimeZone transitions are handled as for round.

Examples

The America/Winnipeg time zone transitioned from Central Standard Time (UTC-6:00) to Central Daylight Time (UTC-5:00) on 2016-03-13, moving directly from 01:59:59 to 03:00:00.

julia> zdt = ZonedDateTime(2016, 3, 13, 1, 45, TimeZone("America/Winnipeg"))
2016-03-13T01:45:00-06:00

julia> ceil(zdt, Dates.Day)
2016-03-14T00:00:00-05:00

julia> ceil(zdt, Dates.Hour)
2016-03-13T03:00:00-05:00

NonExistentTimeError(local_datetime, timezone)

The provided local datetime is does not exist within the specified timezone. Typically occurs on daylight saving time transitions which "spring forward" causing an hour long period to be skipped.

AmbiguousTimeError(local_datetime, timezone)

The provided local datetime is ambiguous within the specified timezone. Typically occurs on daylight saving time transitions which "fall back" causing duplicate hour long period.

UnhandledTimeError(timezone)

The timezone calculation occurs beyond the last calculated transition.

timezone_names() -> Vector{String}

Returns a sorted list of all of the pre-computed time zone names.

all_timezones() -> Vector{TimeZone}

Returns all pre-computed TimeZones.

all_timezones(criteria::Function) -> Vector{TimeZone}

Returns TimeZones that match the given criteria function. The criteria function takes two parameters: UTC transition (DateTime) and transition zone (FixedTimeZone).

Examples

Find all time zones which contain an absolute UTC offset greater than 15 hours:

all_timezones() do dt, zone
    abs(zone.offset.std) > Dates.Second(Dates.Hour(15))
end

Determine all time zones which have a non-hourly daylight saving time offset:

all_timezones() do dt, zone
    zone.offset.dst % Dates.Second(Dates.Hour(1)) != 0
end

timezones_from_abbr(abbr) -> Vector{TimeZone}

Returns all TimeZones that have the specified abbrevation

timezone_abbrs -> Vector{String}

Returns a sorted list of all pre-computed time zone abbrevations.

next_transition_instant(zdt::ZonedDateTime) -> Union{ZonedDateTime, Nothing}
next_transition_instant(tz::TimeZone=localzone()) -> Union{ZonedDateTime, Nothing}

Determine the next instant at which a time zone transition occurs (typically due to daylight-savings time). If no there exists no future transition then nothing will be returned.

Note that the provided ZonedDateTime isn't normally constructable:

julia> instant = next_transition_instant(ZonedDateTime(2018, 3, 1, tz"Europe/London"))
2018-03-25T01:00:00+00:00

julia> instant - Millisecond(1)  # Instant prior to the change
2018-03-25T00:59:59.999+00:00

julia> instant - Millisecond(0)  # Instant after the change
2018-03-25T02:00:00+01:00

julia> ZonedDateTime(2018, 3, 25, 1, tz"Europe/London")  # Cannot normally construct the `instant`
ERROR: NonExistentTimeError: Local DateTime 2018-03-25T01:00:00 does not exist within Europe/London
...

show_next_transition(io::IO=stdout, zdt::ZonedDateTime)
show_next_transition(io::IO=stdout, tz::TimeZone=localzone())

Display useful information about the next time zone transition (typically due to daylight-savings time). Information displayed includes:

• Transition Date: the local date at which the transition occurs (2018-10-28)
• Local Time Change: the way the local clock with change (02:00 falls back to 01:00) and the direction of the change ("Forward" or "Backward")
• Offset Change: the standard offset and DST offset that occurs before and after the transition
• Transition From: the instant before the transition occurs
• Transition To: the instant after the transition occurs

julia> show_next_transition(ZonedDateTime(2018, 8, 1, tz"Europe/London"))
Transition Date:   2018-10-28
Local Time Change: 02:00 → 01:00 (Backward)
Offset Change:     UTC+0/+1 → UTC+0/+0
Transition From:   2018-10-28T01:59:59.999+01:00 (BST)
Transition To:     2018-10-28T01:00:00.000+00:00 (GMT)

julia> show_next_transition(ZonedDateTime(2011, 12, 1, tz"Pacific/Apia"))
Transition Date:   2011-12-30
Local Time Change: 00:00 → 00:00 (Forward)
Offset Change:     UTC-11/+1 → UTC+13/+1
Transition From:   2011-12-29T23:59:59.999-10:00
Transition To:     2011-12-31T00:00:00.000+14:00