TimeZones Internal API

tzdata_url(version="latest") -> AbstractString

Generates a HTTPS URL for the specified tzdata version. Typical version strings are formatted as 4-digit year followed by a lowercase ASCII letter. Available versions start with "tzdata" and are listed on "https://data.iana.org/time-zones/releases/" or "ftp://ftp.iana.org/tz/releases/".

Examples

julia> tzdata_url("2017a")
"https://data.iana.org/time-zones/releases/tzdata2017a.tar.gz"

tzdata_download(version="latest", dir=tempdir()) -> AbstractString

Downloads a tzdata archive from IANA using the specified version to the specified directory. See tzdata_url for details on tzdata version strings.

isarchive(path) -> Bool

Determines if the given path is an archive.

readarchive(archive) -> Vector{AbstractString}

Returns the file names contained in the archive.

extract(archive, directory, [files]; [verbose=false]) -> Nothing

Extracts files from a compressed tar archive to the specified directory. If files is specified only the files given will be extracted. The verbose flag can be used to display additional information to STDOUT.

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) -> Array{ZonedDateTime}

Given a non-existent local DateTime in a TimeZone produces two valid ZonedDateTimes that span the gap. Providing a valid local DateTime returns an empty array. 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.

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)

read_tzfile(io::IO, name::AbstractString) -> TimeZone

Read the content of an I/O stream and process it as a POSIX tzfile. The returned TimeZone will be given the supplied name name unless a FixedTimeZone is returned.

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.