TimeZones Internal API

tzdata_versions() -> Vector{String}

Retrieves all of the currently available tzdata versions from IANA. The version list is ordered from earliest to latest.

Examples

julia> last(tzdata_versions())  # Current latest available tzdata version
"2020a"

tzdata_latest_version() -> String

Determine the latest version of tzdata available while limiting how often we check with remote servers.

tzdata_version_dir(dir::AbstractString) -> AbstractString

Determines the tzdata version by inspecting various files in a directory.

tzdata_version_archive(archive::AbstractString) -> AbstractString

Determines the tzdata version by inspecting the contents within the archive. Useful when downloading the latest archive "tzdata-latest.tar.gz".

read_news(news, [limit]) -> Vector{AbstractString}

Reads all of the tzdata versions from the NEWS file in the order in which they appear. Note that since the NEWS file is in reverse chronological order the versions will also be in that order. Useful for identifying the version of the tzdata.

Resolves a named zone into TimeZone. Updates ordered with any new rules that were required to be ordered.

tryparse_dayofmonth_function(str::AbstractString) -> Union{Function,Nothing}

Parse the various day-of-month formats used within tzdata source files. Returns a function which generates a Date observing the rule. The function returned (f) can be called by providing a year and month arguments or a Date (e.g. f(year, month) or f(::Date)).

julia> f = tryparse_dayofmonth_function("lastSun")
last_sunday_of_month (generic function with 1 method)

julia> f(2019, 3)
2019-03-31

julia> f = tryparse_dayofmonth_function("Sun>=8")
#16 (generic function with 1 method)

julia> f(2019, 3)
2019-03-10

julia> f = tryparse_dayofmonth_function("Fri<=1")
#16 (generic function with 1 method)

julia> f(2019, 4)
2019-03-29

julia> f = tryparse_dayofmonth_function("15")
#18 (generic function with 1 method)

julia> f(2019, 3)
2019-03-15

Rules are typically ordered by the "from" than "in" fields. Since rules also contain a "to" field the written ordering can be problematic for resolving time zone transitions.

Example:

# Rule  NAME    FROM    TO  TYPE    IN  ON  AT      SAVE    LETTER/S
Rule    Poland  1918    1919    -   Sep 16  2:00s   0       -
Rule    Poland  1919    only    -   Apr 15  2:00s   1:00    S
Rule    Poland  1944    only    -   Apr  3  2:00s   1:00    S

A simplistic way of iterating through the rules by years could yield the rules
in the wrong order:

# ON         AT      SAVE    LETTER/S
1918-09-16   2:00s   0       -
1919-09-16   2:00s   0       -
1919-04-15   2:00s   1:00    S
1944-04-03   2:00s   1:00    S

The order_rules function will expand the rules such that they can be ordered by the
"on" date which ensures we process the rules in the correct order:

1918-09-16   2:00s   0       -
1919-04-15   2:00s   1:00    S
1919-09-16   2:00s   0       -
1944-04-03   2:00s   1:00    S

transition_range(dt::DateTime, tz::VariableTimeZone, context::Type{Union{Local,UTC}}) -> UnitRange

Finds the indexes of the tz transitions which may be applicable for the dt. The given DateTime is expected to be local to the time zone or in UTC as specified by context. Note that UTC context will always return a range of length one.

interpret(dt::DateTime, tz::VariableTimeZone, context::Type{Union{Local,UTC}}) -> Array{ZonedDateTime}

Produces a list of possible ZonedDateTimes given a DateTime and VariableTimeZone. The result will be returned in chronological order. Note that DateTimes in the local context typically return 0-2 results while the UTC context will always return 1 result.

shift_gap(local_dt::DateTime, tz::VariableTimeZone) -> Tuple

Given a non-existent local DateTime in a TimeZone produces a tuple containing two valid ZonedDateTimes that span the gap. Providing a valid local DateTime returns an empty tuple. Note that this function does not support passing in a UTC DateTime since there are no non-existent UTC DateTimes.

Aside: the function name refers to a period of invalid local time (gap) caused by daylight saving time or offset changes (shift).

first_valid(local_dt::DateTime, tz::VariableTimeZone, step::Period)

Construct a valid ZonedDateTime by adjusting the local DateTime. If the local DateTime is non-existent then it will be adjusted using the step to be after the gap. When the local DateTime is ambiguous the first ambiguous DateTime will be returned.

last_valid(local_dt::DateTime, tz::VariableTimeZone, step::Period)

Construct a valid ZonedDateTime by adjusting the local DateTime. If the local DateTime is non-existent then it will be adjusted using the step to be before the gap. When the local DateTime is ambiguous the last ambiguous DateTime will be returned.

TZFile.read(io::IO) -> Function

Read the content of an I/O stream as a POSIX tzfile to produce a TimeZone. As the tzfile format does not include the name of the interpreted time zone this function returns a closure which takes the single argument name::AbstractString and when called produces a TimeZone instance.

TZFile.write(io::IO, tz::TimeZone; version::Char=TZFile.WRITE_VERSION)

Writes the time zone to the I/O stream in the POSIX tzfile format.

UTCOffset

A UTCOffset is an amount of time subtracted from or added to UTC to get the current local time – whether it's standard time or daylight saving time.

@optional(expr)

Creates multiple method signatures to allow optional arguments before required arguments. For example:

f(a=1, b=2, c) = ...

becomes:

f(a, b, c) = ...
f(a, c) = f(a, 2, c)
f(c) = f(1, 2, c)

parse_tz_format(str) -> TimeZone

Parse the time zone format typically provided via the "TZ" environment variable. Details on the format can be found under the man page for tzset.

tryparse_tz_format(str) -> Union{TimeZone, Nothing}

Like parse_tz_format, but returns either a value of the TimeZone, or nothing if the string does not contain a valid format.

hash(::ZonedDateTime, h)

Compute an integer hash code for a ZonedDateTime by hashing the utc_datetime field. hash(:utc_instant, h) is used to avoid collisions with DateTime hashes.

guess(start::ZonedDateTime, finish::ZonedDateTime, step) -> Integer

Given a start and end date, indicates how many steps/periods are between them. Defining this function allows StepRanges to be defined for ZonedDateTimes.