This PR adds a note to the Zoned::now() documentation describing the
best way to create a Zoned for the current time in a time zone that
isn't the system time zone. Unfortunately, one intuitive route is
Zoned::now().with_time_zone(), but this 1) fetches the system time
zone, which isn't free and 2) computes the civil datetime for the system
time zone, which is not necessary here. Instead,
Timestamp::now().to_zoned() is a more direct approach that doesn't do
any unnecessary work.
I decided to go this route instead of adding a new API as requested
in #93. In particular, I think the API suggested in #93 is a bit clunky,
and is likely to lead to the addition of other even clunkier APIs as
well. While using a Timestamp might require an extra import, it does
have the benefit of being compositional. I'd like to encourage that
instead of adding a bunch of alternative constructors.
Moreoever, I feel like the Jiff API overall does a good job of avoiding
lots of different constructors that I usually find somewhat confusing in
other APIs. We might eventually have to give into that depending on use
cases, but I think for this here, a documentation note suffices.
This PR adds a note to the
Zoned::now()documentation describing the best way to create aZonedfor the current time in a time zone that isn't the system time zone. Unfortunately, one intuitive route isZoned::now().with_time_zone(), but this 1) fetches the system time zone, which isn't free and 2) computes the civil datetime for the system time zone, which is not necessary here. Instead,Timestamp::now().to_zoned()is a more direct approach that doesn't do any unnecessary work.I decided to go this route instead of adding a new API as requested in #93. In particular, I think the API suggested in #93 is a bit clunky, and is likely to lead to the addition of other even clunkier APIs as well. While using a
Timestampmight require an extra import, it does have the benefit of being compositional. I'd like to encourage that instead of adding a bunch of alternative constructors.Moreoever, I feel like the Jiff API overall does a good job of avoiding lots of different constructors that I usually find somewhat confusing in other APIs. We might eventually have to give into that depending on use cases, but I think for this here, a documentation note suffices.
Closes #93, Closes #94