TimeZones Public API

TimeZone

Dates.TimeZoneMethod
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
source
TimeZones.@tz_strMacro
@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)
source
TimeZones.localzoneFunction
localzone() -> TimeZone

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

source
TimeZones.buildFunction
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. "2023c"). The force flag is used to re-download tzdata archives.

Warning

This function is not thread-safe and meant primarily for experimentation.

source

Legacy Time Zones

Dates.TimeZoneMethod
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)
source
TimeZones.ClassType
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.
source
TimeZones.istimezoneFunction
istimezone(str::AbstractString, mask::Class=Class(:DEFAULT)) -> Bool

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

source

ZonedDateTime

TimeZones.ZonedDateTimeType
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.

source
TimeZones.ZonedDateTimeMethod
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.

source
TimeZones.ZonedDateTimeMethod
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.

source
TimeZones.ZonedDateTimeMethod
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.

source
TimeZones.ZonedDateTimeMethod
ZonedDateTime(date::Date, ...)
ZonedDateTime(date::Date, time::Time, ...)

Construct a ZonedDateTime from Date and Time arguments.

source
TimeZones.astimezoneFunction
astimezone(zdt::ZonedDateTime, tz::TimeZone) -> ZonedDateTime

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

source
TimeZones.FixedTimeZoneMethod
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)
source
Dates.DateTimeMethod
DateTime(zdt::ZonedDateTime) -> DateTime

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

Warning

Any arithmetic performed on the returned DateTime will be timezone unaware and will not reflect an accurate local time if the operation would cross a DST transition.

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
source
Dates.DateTimeMethod
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
source
Dates.DateMethod
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
source
Dates.DateMethod
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
source
Dates.TimeMethod
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
source
Dates.TimeMethod
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
source

Current Time

Dates.todayMethod
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)
source
TimeZones.todayatFunction
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
source

Rounding

Base.roundMethod
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
source
Base.floorMethod
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
source
Base.ceilMethod
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
source

Exceptions

TimeZones.NonExistentTimeErrorType
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.

source
TimeZones.AmbiguousTimeErrorType
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.

source

Discovery

TimeZones.all_timezonesFunction
all_timezones() -> Vector{TimeZone}

Returns all pre-computed TimeZones.

source
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
source
TimeZones.next_transition_instantFunction
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
...
source
TimeZones.show_next_transitionFunction
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
source