From f8dc8d6e829b3997ae092225b02e877636bda6bb Mon Sep 17 00:00:00 2001 From: Curtis Vogt Date: Thu, 21 Mar 2024 22:39:24 -0500 Subject: [PATCH] Improve conversion docstrings (#453) --- src/conversions.jl | 70 +++++++++++++++++++++++++++++++++------------- 1 file changed, 50 insertions(+), 20 deletions(-) diff --git a/src/conversions.jl b/src/conversions.jl index 786bdff76..d3d49b116 100644 --- a/src/conversions.jl +++ b/src/conversions.jl @@ -8,13 +8,20 @@ const utc_tz = FixedTimeZone("UTC") """ DateTime(zdt::ZonedDateTime) -> DateTime -Create a `DateTime` by dropping the associated time zone. Effectively, this new `DateTime` -is implicitly associated with `timezone(zdt)`. +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})`](@ref). # Example ```jldoctest -julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"UTC-4") +julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"America/New_York") 2014-05-30T21:00:00-04:00 julia> DateTime(zdt) @@ -26,12 +33,14 @@ Dates.DateTime(zdt::ZonedDateTime) = zdt.utc_datetime + zdt.zone.offset """ DateTime(zdt::ZonedDateTime, ::Type{UTC}) -> DateTime -Create a `DateTime` which is implicitly associated with UTC. +Construct a `DateTime` based on the UTC representation of the provided `ZonedDateTime`. + +See also: [`DateTime(::ZonedDateTime)`](@ref). # Example ```jldoctest -julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"UTC-4") +julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"America/New_York") 2014-05-30T21:00:00-04:00 julia> DateTime(zdt, UTC) @@ -44,13 +53,14 @@ Dates.DateTime(zdt::ZonedDateTime, ::Type{UTC}) = zdt.utc_datetime """ Date(zdt::ZonedDateTime) -> Date -Create a `Date` by dropping the associated time zone. Effectively, this new `Date` -is implicitly associated with `timezone(zdt)`. +Construct a `Date` based on the "local time" representation of the provided `ZonedDateTime`. + +See also: [`Date(::ZonedDateTime, ::Type{UTC})`](@ref). # Example ```jldoctest -julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"UTC-4") +julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"America/New_York") 2014-05-30T21:00:00-04:00 julia> Date(zdt) @@ -63,12 +73,14 @@ Dates.Date(zdt::ZonedDateTime) = Date(DateTime(zdt)) """ Date(zdt::ZonedDateTime, ::Type{UTC}) -> Date -Create a `Date` which is implicitly associated with UTC. +Construct a `Date` based on the UTC representation of the provided `ZonedDateTime`. + +See also: [`Date(::ZonedDateTime)`](@ref). # Example ```jldoctest -julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"UTC-4") +julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"America/New_York") 2014-05-30T21:00:00-04:00 julia> Date(zdt, UTC) @@ -81,13 +93,14 @@ Dates.Date(zdt::ZonedDateTime, ::Type{UTC}) = Date(DateTime(zdt, UTC)) """ Time(zdt::ZonedDateTime) -> Time -Create a `Time` by dropping the associated time zone. Effectively, this new `Time` -is implicitly associated with `timezone(zdt)`. +Construct a `Time` based on the "local time" representation of the provided `ZonedDateTime`. + +See also: [`Time(::ZonedDateTime, ::Type{UTC})`](@ref). # Example ```jldoctest -julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"UTC-4") +julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"America/New_York") 2014-05-30T21:00:00-04:00 julia> Time(zdt) @@ -100,12 +113,14 @@ Dates.Time(zdt::ZonedDateTime) = Time(DateTime(zdt)) """ Time(zdt::ZonedDateTime, ::Type{UTC}) -> Date -Create a `Time` which is implicitly associated with UTC. +Construct a `Time` based on the UTC representation of the provided `ZonedDateTime`. + +See also: [`Time(::ZonedDateTime)`](@ref). # Example ```jldoctest -julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"UTC-4") +julia> zdt = ZonedDateTime(2014, 5, 30, 21, tz"America/New_York") 2014-05-30T21:00:00-04:00 julia> Time(zdt, UTC) @@ -118,7 +133,9 @@ Dates.Time(zdt::ZonedDateTime, ::Type{UTC}) = Time(DateTime(zdt, UTC)) """ now(::TimeZone) -> ZonedDateTime -Returns a `ZonedDateTime` corresponding to the user's system time in the specified `TimeZone`. +Create a `ZonedDateTime` corresponding to the current system time in the specified `TimeZone`. + +See also: [`today(::TimeZone)`](@ref), [`todayat(::TimeZone)`](@ref). """ function Dates.now(tz::TimeZone) utc = unix2datetime(time()) @@ -128,7 +145,9 @@ end """ today(tz::TimeZone) -> Date -Returns the date portion of `now(tz)` in local time. +Create the current `Date` in the specified `TimeZone`. Equivalent to `Date(now(tz))`. + +See also: [`now(::TimeZone)`](@ref), [`todayat(::TimeZone)`](@ref). # Examples @@ -146,19 +165,30 @@ julia> today(tz"Pacific/Midway"), today(tz"Pacific/Apia") Dates.today(tz::TimeZone) = Date(now(tz)) """ - todayat(tod::Time, tz::TimeZone, [amb]) -> ZonedDateTime + 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)`](@ref), [`today(::TimeZone)`](@ref). + # Examples ```julia julia> today(tz"Europe/Warsaw") -2017-11-09 +2017-10-29 julia> todayat(Time(10, 30), tz"Europe/Warsaw") -2017-11-09T10:30:00+01:00 +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 ``` """ function todayat(tod::Time, tz::VariableTimeZone, amb::Union{Integer,Bool})