There used to be multiple modules like `chrono::datetime` which only
provide a single type `DateTime`. In retrospect, this module structure
never reflected how people use those types; with the release of 0.3.0
`chrono::prelude` is a preferred way to glob-import types, and due to
reexports `chrono::DateTime` and likes are also common enough.
Therefore this commit removes those implementation modules and
flattens the module structure. Specifically:
Before After
---------------------------------- ----------------------------
chrono:📅:Date chrono::Date
chrono:📅:MIN chrono::MIN_DATE
chrono:📅:MAX chrono::MAX_DATE
chrono::datetime::DateTime chrono::DateTime
chrono::datetime::TsSeconds chrono::TsSeconds
chrono::datetime::serde::* chrono::serde::*
chrono::naive::time::NaiveTime chrono::naive::NaiveTime
chrono::naive:📅:NaiveDate chrono::naive::NaiveDate
chrono::naive:📅:MIN chrono::naive::MIN_DATE
chrono::naive:📅:MAX chrono::naive::MAX_DATE
chrono::naive::datetime::NaiveDateTime
chrono::naive::NaiveDateTime
chrono::naive::datetime::TsSeconds chrono::naive::TsSeconds
chrono::naive::datetime::serde::* chrono::naive::serde::*
chrono::offset::utc::UTC chrono::offset::UTC
chrono::offset::fixed::FixedOffset chrono::offset::FixedOffset
chrono::offset::local::Local chrono::offset::Local
chrono::format::parsed::Parsed chrono::format::Parsed
All internal documentation links have been updated (phew!) and
verified with LinkChecker [1]. Probably we can automate this check
in the future.
[1] https://wummel.github.io/linkchecker/Closes#161. Compared to the original proposal, `chrono::naive` is
retained as we had `TsSeconds` types duplicated for `NaiveDateTime`
and `DateTime` (legitimately).
This may sound strange, but the final type for the offset "value" was
originally `time::Duration` (returned by `Offset::local_minus_utc`).
This caused a lot of problems becaus adding `Duration` fully interacts
with leap seconds and `Duration` itself is somewhat deprecated.
This commit entirely replaces this role of `Duration` with
`FixedOffset`. So if we had `Offset` and `Duration` to represent
the "storage" offset type and the offset "value" in the past,
we now have `Offset` and `FixedOffset`. Storage-to-value conversion is
called to "fix" the offset---an apt term for the type.
The list of actual changes:
- The time zone offset is now restricted to UTC-23:59:59 through
UTC+23:59:59, and no subsecond value is allowed. As described above,
`FixedOffset` is now fully used for this purpose.
- One can now add and subtract `FixedOffset` to/from timelike values.
Replaces a temporary `chrono::offset::add_with_leapsecond` function.
Datelike & non-timelike values are never affected by the offset.
- UTC and local views to `Date<Tz>` are now identical. We keep
relevant methods for the consistency right now.
- `chrono::format::format` now receives `FixedOffset` in place of
`(Old)Duration`.
- `Offset` now has a `fix` method to resolve, or to "fix" the
"storage" offset (`Offset`) to the offset "value" (`FixedOffset`).
- `FixedOffset::{local_minus_utc, utc_minus_local}` methods are added.
They no longer depend on `Duration` as well.
Due to the backward compatibility we won't be going to remove support
for `time::Duration` in 0.3, and the initial 0.3.0 release won't have
proper `std::time::Duration` support (haven't finalized the logics).
However we will reserve proper names and signatures for the upcoming
`std::time::Duration` support---the "older" duration type will be
referred as "signed" in the names.
- Added a `chrono::prelude` module. This does not have the (old)
`Duration` type reexported, so the documentation has now correctly
replaced all occurrences of `chrono::Duration`. The existing
`chrono::Duration` reexport itself remains for the compatibility.
- Avoided using a plain `Duration` type in the signature, to avoid
any ambiguity.
- Renamed `checked_{add,sub}` to `checked_{add,sub}_signed`.
- Subtraction operator between two instants has been removed and
replaced with `signed_duration_since`. This follows the naming
chosen by `std::time::SystemTime` etc., and the version for newer
`std::time::Duration` will be named to `duration_since`.
This provides examples for most of the constructor-like methods on
`TimeZone`, examples on the various `Offset` impls, and links
`NaiveDateTime` to `TimeZone` so that it's more obvious how you're
supposed to do things.
This is related to #88, which is something that I ran into when I
started using rust-chrono.
While writing documentation tests for NaiveTime it was found that
the addition involving leap seconds is *still* slightly broken.
(A consequence of having less tests, well.) The addition routine
has been rewritten to be explicit about leap seconds while passing
all other tests, so the rewrite does not change the intention.
`Time` with an associated time zone is in principle possible, but
in practice it can only meaningfully constructed from an existing
`DateTime`. this makes it hard to implement other operations
natural to `NaiveTime` for `Time` (e.g. `with_*` methods), so
we simply let it go.
migration path: if you *do* happen to use `Time`, don't panic!
every operation possible to `Time` is much more possible to
`NaiveTime`. if you have to deal with a local time, first combine
it with a `NaiveDate`, convert it via `TimeZone::from_local_datetime`
then extract `Time` part again.
this is partly because... we are using the simple name `timestamp`
in the `Parsed` anyway. that value is so widespread enough that
its name can be simply THE timestamp. old methods have been marked
deprecated.
- We have splitted `Offset` into `Offset` and `OffsetState` (name
changes in consideration). The former is used to construct and convert
local or UTC date, and the latter is used to store the UTC offset
inside constructed values. Some offsets are their own states as well.
- This uses lots of associated types which implementation is still in
flux. Currently it crashes with debuginfo enabled. We've temporarily
disabled debuginfo from `Cargo.toml`.
- This technically allows a conversion to the local time, but not yet
tested.
Kang Seonghoon
Richard Petrie
Brandon W Maister
János Illés
Jisoo Park