Skip to content

Commit

Permalink
zoned: add note about Timestamp::now().to_zoned()
Browse files Browse the repository at this point in the history
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.

Closes #93, Closes #94
  • Loading branch information
BurntSushi committed Aug 24, 2024
1 parent 0e569cb commit 57e5e41
Showing 1 changed file with 6 additions and 0 deletions.
6 changes: 6 additions & 0 deletions src/zoned.rs
Original file line number Diff line number Diff line change
Expand Up @@ -384,6 +384,12 @@ impl Zoned {
/// compatible with the `log` crate and enable Jiff's `logging` Cargo
/// feature.)
///
/// To create a `Zoned` value for the current time in a particular
/// time zone other than the system default time zone, use
/// `Timestamp::now().to_zoned(time_zone)`. In particular, using
/// [`Timestamp::now`] avoids the work required to fetch the system time
/// zone if you did `Zoned::now().with_time_zone(time_zone)`.
///
/// # Panics
///
/// This panics if the system clock is set to a time value outside of the
Expand Down

0 comments on commit 57e5e41

Please sign in to comment.