From 70acadf85f5f40929f01cf181d4e62602dfccc59 Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Fri, 26 Apr 2024 02:45:33 +0000 Subject: [PATCH] build based on 18915aa --- dev/api-private/index.html | 8 ++++---- dev/api-public/index.html | 40 +++++++++++++++++++------------------- dev/arithmetic/index.html | 2 +- dev/conversions/index.html | 2 +- dev/current/index.html | 2 +- dev/faq/index.html | 2 +- dev/index.html | 2 +- dev/rounding/index.html | 2 +- dev/search/index.html | 2 +- dev/types/index.html | 2 +- 10 files changed, 32 insertions(+), 32 deletions(-) diff --git a/dev/api-private/index.html b/dev/api-private/index.html index 7ed7013e..96db5538 100644 --- a/dev/api-private/index.html +++ b/dev/api-private/index.html @@ -1,6 +1,6 @@ API – Private · TimeZones.jl
Edit on GitHub

TimeZones Internal API

TZData

TimeZones.TZData.tzdata_versions — Function
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"
source
TimeZones.TZData.tzdata_version_archive — Function
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".

source
TimeZones.TZData.read_news — Function
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.

source
TimeZones.TZData.tryparse_dayofmonth_function — Function
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")
+"2020a"
source
TimeZones.TZData.tzdata_version_archive — Function
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".

source
TimeZones.TZData.read_news — Function
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.

source
TimeZones.TZData.tryparse_dayofmonth_function — Function
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)
@@ -22,7 +22,7 @@
 #18 (generic function with 1 method)
 
 julia> f(2019, 3)
-2019-03-15
source
TimeZones.TZData.order_rules — Function

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
+2019-03-15
source
TimeZones.TZData.order_rules — Function

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
@@ -42,6 +42,6 @@
 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
source

Interpretation

TimeZones.transition_range — Function
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.

source
TimeZones.interpret — Function
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.

source
TimeZones.shift_gap — Function
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).

source
TimeZones.first_valid — Function
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.

source
TimeZones.last_valid — Function
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.

source

TZFile

TimeZones.TZFile.read — Function
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.

source

Etc.

TimeZones.UTCOffset — Type
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.

source
TimeZones.@optional — Macro
@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) = ...
+1944-04-03   2:00s   1:00    S
source

Interpretation

TimeZones.transition_range — Function
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.

source
TimeZones.interpret — Function
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.

source
TimeZones.shift_gap — Function
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).

source
TimeZones.first_valid — Function
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.

source
TimeZones.last_valid — Function
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.

source

TZFile

TimeZones.TZFile.read — Function
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.

source

Etc.

TimeZones.UTCOffset — Type
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.

source
TimeZones.@optional — Macro
@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)
source
TimeZones.parse_tz_format — Function
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.

source
TimeZones.tryparse_tz_format — Function
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.

source
Base.hash — Method
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.

source
Dates.guess — Method
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.

source
+f(c) = f(1, 2, c)source
TimeZones.parse_tz_format — Function
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.

source
TimeZones.tryparse_tz_format — Function
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.

source
Base.hash — Method
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.

source
Dates.guess — Method
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.

source
diff --git a/dev/api-public/index.html b/dev/api-public/index.html index 452ad2e1..802f06fa 100644 --- a/dev/api-public/index.html +++ b/dev/api-public/index.html @@ -3,17 +3,17 @@ Europe/Warsaw (UTC+1/UTC+2) julia> TimeZone("UTC") -UTCsource
TimeZones.@tz_str — Macro
@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.localzone — Function
localzone() -> TimeZone

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

source
TimeZones.FixedTimeZone — Type
FixedTimeZone

A TimeZone with a constant offset for all of time.

source
TimeZones.VariableTimeZone — Type
VariableTimeZone

A TimeZone with an offset that changes over time.

source
TimeZones.build — Function
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.TimeZone — Method
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")
+UTC
source
TimeZones.@tz_str — Macro
@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.localzone — Function
localzone() -> TimeZone

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

source
TimeZones.FixedTimeZone — Type
FixedTimeZone

A TimeZone with a constant offset for all of time.

source
TimeZones.VariableTimeZone — Type
VariableTimeZone

A TimeZone with an offset that changes over time.

source
TimeZones.build — Function
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.TimeZone — Method
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.Class — Type
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.istimezone — Function
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.ZonedDateTime — Type
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.ZonedDateTime — Method
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.ZonedDateTime — Method
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.ZonedDateTime — Method
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.ZonedDateTime — Method
ZonedDateTime(date::Date, ...)
-ZonedDateTime(date::Date, time::Time, ...)

Construct a ZonedDateTime from Date and Time arguments.

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

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

source
TimeZones.timezone — Method
timezone(::ZonedDateTime) -> TimeZone

Returns the TimeZone used by the ZonedDateTime.

source
Dates.TimeZone — Method
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")
+US/Pacific (UTC-8/UTC-7)
source
TimeZones.Class — Type
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.istimezone — Function
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.ZonedDateTime — Type
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.ZonedDateTime — Method
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.ZonedDateTime — Method
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.ZonedDateTime — Method
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.ZonedDateTime — Method
ZonedDateTime(date::Date, ...)
+ZonedDateTime(date::Date, time::Time, ...)

Construct a ZonedDateTime from Date and Time arguments.

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

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

source
TimeZones.timezone — Method
timezone(::ZonedDateTime) -> TimeZone

Returns the TimeZone used by the ZonedDateTime.

source
Dates.TimeZone — Method
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)
source
TimeZones.FixedTimeZone — Method
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")
+America/New_York (UTC-5/UTC-4)
source
TimeZones.FixedTimeZone — Method
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)
@@ -23,38 +23,38 @@
 2014-02-18T06:00:00-05:00
 
 julia> FixedTimeZone(zdt2)
-EST (UTC-5)
source
Dates.DateTime — Method
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")
+EST (UTC-5)
source
Dates.DateTime — Method
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.DateTime — Method
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
source
Dates.DateTime — Method
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.Date — Method
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-31T01:00:00
source
Dates.Date — Method
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.Date — Method
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-30
source
Dates.Date — Method
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.Time — Method
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-31
source
Dates.Time — Method
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.Time — Method
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")
+21:00:00
source
Dates.Time — Method
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.now — Method
now(::TimeZone) -> ZonedDateTime

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

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

source
Dates.today — Method
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")
+01:00:00
source

Current Time

Dates.now — Method
now(::TimeZone) -> ZonedDateTime

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

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

source
Dates.today — Method
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.todayat — Function
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-11-09, 2017-11-10)
source
TimeZones.todayat — Function
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")
@@ -67,7 +67,7 @@
 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.round — Method
round(zdt::ZonedDateTime, p::Period, [r::RoundingMode]) -> ZonedDateTime
+2017-10-29T02:00:00+01:00
source

Rounding

Base.round — Method
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
 
@@ -82,7 +82,7 @@
 1996-10-26T00:00:00+06:30
 
 julia> round(zdt, Dates.Day)
-ERROR: Local DateTime 1996-10-26T00:00:00 is ambiguous
source
Base.floor — Method
floor(zdt::ZonedDateTime, p::Period) -> ZonedDateTime
+ERROR: Local DateTime 1996-10-26T00:00:00 is ambiguous
source
Base.floor — Method
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
 
@@ -90,7 +90,7 @@
 2016-03-13T00:00:00-06:00
 
 julia> floor(zdt, Dates.Hour)
-2016-03-13T01:00:00-06:00
source
Base.ceil — Method
ceil(zdt::ZonedDateTime, p::Period) -> ZonedDateTime
+2016-03-13T01:00:00-06:00
source
Base.ceil — Method
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
 
@@ -98,11 +98,11 @@
 2016-03-14T00:00:00-05:00
 
 julia> ceil(zdt, Dates.Hour)
-2016-03-13T03:00:00-05:00
source

Exceptions

TimeZones.NonExistentTimeError — Type
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.AmbiguousTimeError — Type
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
TimeZones.UnhandledTimeError — Type
UnhandledTimeError(timezone)

The timezone calculation occurs beyond the last calculated transition.

source

Discovery

TimeZones.timezone_names — Function
timezone_names() -> Vector{String}

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

source
TimeZones.all_timezones — Function
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
+2016-03-13T03:00:00-05:00
source

Exceptions

TimeZones.NonExistentTimeError — Type
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.AmbiguousTimeError — Type
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
TimeZones.UnhandledTimeError — Type
UnhandledTimeError(timezone)

The timezone calculation occurs beyond the last calculated transition.

source

Discovery

TimeZones.timezone_names — Function
timezone_names() -> Vector{String}

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

source
TimeZones.all_timezones — Function
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.timezones_from_abbr — Function
timezones_from_abbr(abbr) -> Vector{TimeZone}

Returns all TimeZones that have the specified abbrevation

source
TimeZones.timezone_abbrs — Function
timezone_abbrs -> Vector{String}

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

source
TimeZones.next_transition_instant — Function
next_transition_instant(zdt::ZonedDateTime) -> Union{ZonedDateTime, Nothing}
+end
source
TimeZones.timezones_from_abbr — Function
timezones_from_abbr(abbr) -> Vector{TimeZone}

Returns all TimeZones that have the specified abbrevation

source
TimeZones.timezone_abbrs — Function
timezone_abbrs -> Vector{String}

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

source
TimeZones.next_transition_instant — Function
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
 
@@ -114,7 +114,7 @@
 
 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_transition — Function
show_next_transition(io::IO=stdout, zdt::ZonedDateTime)
+...
source
TimeZones.show_next_transition — Function
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)
@@ -127,4 +127,4 @@
 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
+Transition To: 2011-12-31T00:00:00.000+14:00source diff --git a/dev/arithmetic/index.html b/dev/arithmetic/index.html index d9a7679a..388ea483 100644 --- a/dev/arithmetic/index.html +++ b/dev/arithmetic/index.html @@ -52,4 +52,4 @@ 2016-01-01T14:00:00+00:00 2016-01-01T15:00:00+00:00 2016-01-01T16:00:00+00:00 - 2016-01-01T17:00:00+00:00

Note that 2016-01-01T17:00:00 in UTC corresponds to 2016-01-01T18:00:00 in "Europe/Warsaw", which is the requested endpoint of the range.

+ 2016-01-01T17:00:00+00:00

Note that 2016-01-01T17:00:00 in UTC corresponds to 2016-01-01T18:00:00 in "Europe/Warsaw", which is the requested endpoint of the range.

diff --git a/dev/conversions/index.html b/dev/conversions/index.html index d3fb59cc..c89cca8f 100644 --- a/dev/conversions/index.html +++ b/dev/conversions/index.html @@ -66,4 +66,4 @@ "20150806+02:00" julia> Dates.format(zdt, "yyyy-mm-dd HH:MM ZZZ") -"2015-08-06 22:25 CEST" +"2015-08-06 22:25 CEST" diff --git a/dev/current/index.html b/dev/current/index.html index dc06a1bb..89d53fd2 100644 --- a/dev/current/index.html +++ b/dev/current/index.html @@ -1,2 +1,2 @@ -Current Time · TimeZones.jl
Edit on GitHub

Current Time

now / System Time Zone

Julia provides the now() method to retrieve your current system's time as a DateTime. The TimeZones.jl package provides an additional now(::TimeZone) method providing the current time as a ZonedDateTime:

now(tz"Europe/Warsaw")

To get the TimeZone currently specified on you system you can use localzone(). Combining this method with the new now method produces the current system time in the current system's time zone:

now(localzone())

today

Similar to now the TimeZones package also provides a today(::TimeZone) method which allows you to determine the current date as a Date in the specified TimeZone.

julia> a, b = now(tz"Pacific/Midway"), now(tz"Pacific/Apia")(ZonedDateTime(2024, 4, 25, 15, 25, 27, 656, tz"Pacific/Midway"), ZonedDateTime(2024, 4, 26, 15, 25, 27, 656, tz"Pacific/Apia"))
julia> a - b0 milliseconds
julia> today(tz"Pacific/Midway"), today(tz"Pacific/Apia")(Date("2024-04-25"), Date("2024-04-26"))

You should be careful not to use today() when working with ZonedDateTimes as you may end up using the wrong day. For example:

julia> midway, apia = tz"Pacific/Midway", tz"Pacific/Apia"(tz"Pacific/Midway", tz"Pacific/Apia")
julia> ZonedDateTime(today() + Time(11), midway)2024-04-26T11:00:00-11:00
julia> ZonedDateTime(today() + Time(11), apia)  # Wrong date; with the current rules apia should be one day ahead of midway2024-04-26T11:00:00+13:00
julia> ZonedDateTime(today(midway) + Time(11), midway)2024-04-25T11:00:00-11:00
julia> ZonedDateTime(today(apia) + Time(11), apia)2024-04-26T11:00:00+13:00

Alternatively, you can use the todayat function which takes care of this for you:

julia> todayat(Time(11), tz"Pacific/Midway")2024-04-25T11:00:00-11:00
julia> todayat(Time(11), tz"Pacific/Apia")2024-04-26T11:00:00+13:00
+Current Time · TimeZones.jl
Edit on GitHub

Current Time

now / System Time Zone

Julia provides the now() method to retrieve your current system's time as a DateTime. The TimeZones.jl package provides an additional now(::TimeZone) method providing the current time as a ZonedDateTime:

now(tz"Europe/Warsaw")

To get the TimeZone currently specified on you system you can use localzone(). Combining this method with the new now method produces the current system time in the current system's time zone:

now(localzone())

today

Similar to now the TimeZones package also provides a today(::TimeZone) method which allows you to determine the current date as a Date in the specified TimeZone.

julia> a, b = now(tz"Pacific/Midway"), now(tz"Pacific/Apia")(ZonedDateTime(2024, 4, 25, 15, 45, 7, 800, tz"Pacific/Midway"), ZonedDateTime(2024, 4, 26, 15, 45, 7, 800, tz"Pacific/Apia"))
julia> a - b0 milliseconds
julia> today(tz"Pacific/Midway"), today(tz"Pacific/Apia")(Date("2024-04-25"), Date("2024-04-26"))

You should be careful not to use today() when working with ZonedDateTimes as you may end up using the wrong day. For example:

julia> midway, apia = tz"Pacific/Midway", tz"Pacific/Apia"(tz"Pacific/Midway", tz"Pacific/Apia")
julia> ZonedDateTime(today() + Time(11), midway)2024-04-26T11:00:00-11:00
julia> ZonedDateTime(today() + Time(11), apia)  # Wrong date; with the current rules apia should be one day ahead of midway2024-04-26T11:00:00+13:00
julia> ZonedDateTime(today(midway) + Time(11), midway)2024-04-25T11:00:00-11:00
julia> ZonedDateTime(today(apia) + Time(11), apia)2024-04-26T11:00:00+13:00

Alternatively, you can use the todayat function which takes care of this for you:

julia> todayat(Time(11), tz"Pacific/Midway")2024-04-25T11:00:00-11:00
julia> todayat(Time(11), tz"Pacific/Apia")2024-04-26T11:00:00+13:00
diff --git a/dev/faq/index.html b/dev/faq/index.html index 9a7d44a6..273058c7 100644 --- a/dev/faq/index.html +++ b/dev/faq/index.html @@ -28,4 +28,4 @@ TimeZones.TZData.compile(max_year=2220) ZonedDateTime(DateTime(2215), TimeZone("Europe/Warsaw")) end -2215-01-01T00:00:00+01:00 +2215-01-01T00:00:00+01:00 diff --git a/dev/index.html b/dev/index.html index 2cebc0ca..069c3de0 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,4 +1,4 @@ Introduction · TimeZones.jl
Edit on GitHub

Time Zones

TimeZones.jl provides access to the IANA time zone database (also referred to as the tz database) to the programming language Julia. This library can handle any time zone in the tz database but some have excluded by default due to them being deemed as historical (such as "Etc/*").

Installation

The TimeZones package extends the Dates module provided by Julia version 0.4. In order to use this package you will need to have Julia 0.4 or higher installed on your system. Details on downloading and installing Julia can be found on the language homepage.

Once Julia is installed you can simply install TimeZones using the package manager. First open a Julia interactive session and run:

julia> using Pkg  # on Julia 0.7+
 
-julia> Pkg.add("TimeZones")

This command will install the latest version of TimeZones, automatically download the latest tz database, and convert the data into an Julia optimized format.

+julia> Pkg.add("TimeZones")

This command will install the latest version of TimeZones, automatically download the latest tz database, and convert the data into an Julia optimized format.

diff --git a/dev/rounding/index.html b/dev/rounding/index.html index 9fe5a56a..c2274d2e 100644 --- a/dev/rounding/index.html +++ b/dev/rounding/index.html @@ -25,4 +25,4 @@ 1996-10-26T00:00:00+06:30 julia> round(zdt, Dates.Day) -ERROR: AmbiguousTimeError: Local DateTime 1996-10-26T00:00:00 is ambiguous within Asia/Colombo +ERROR: AmbiguousTimeError: Local DateTime 1996-10-26T00:00:00 is ambiguous within Asia/Colombo diff --git a/dev/search/index.html b/dev/search/index.html index b06a701a..4321cdf5 100644 --- a/dev/search/index.html +++ b/dev/search/index.html @@ -1,2 +1,2 @@ -Search · TimeZones.jl

Loading search...

    +Search · TimeZones.jl

    Loading search...

      diff --git a/dev/types/index.html b/dev/types/index.html index a84b8308..a69cfd1a 100644 --- a/dev/types/index.html +++ b/dev/types/index.html @@ -46,4 +46,4 @@ FixedTimeZone("-04:30") FixedTimeZone("+12:34:56") FixedTimeZone("FOO", -6 * 3600) # 6 hours in seconds

      Constructing a ZonedDateTime works similarly to VariableTimeZone:

      julia> ZonedDateTime(1960, 1, 1, tz"UTC")
-1960-01-01T00:00:00+00:00
      +1960-01-01T00:00:00+00:00