From 2cd9797ea6fd1b9085b83bd34333d1d224fc77ed Mon Sep 17 00:00:00 2001 From: Nikhil Benesch Date: Sat, 26 Sep 2020 10:57:33 -0400 Subject: [PATCH] Update duration docs for oldtime feature (#484) The main crate docs made some claims about the Duration type that became incorrect with the new oldtime feature (#478). Per @jhpratt. --- README.md | 17 ++++++++++++----- src/lib.rs | 17 ++++++++++++----- 2 files changed, 24 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 23bd952158..5a5a74b42a 100644 --- a/README.md +++ b/README.md @@ -77,15 +77,22 @@ See the [cargo docs][] for examples of specifying features. ### Duration -Chrono currently uses -the [`time::Duration`](https://docs.rs/time/0.1.40/time/struct.Duration.html) type -from the `time` crate to represent the magnitude of a time span. -Since this has the same name as the newer, standard type for duration, -the reference will refer this type as `OldDuration`. +Chrono currently uses its own [`Duration`] type to represent the magnitude +of a time span. Since this has the same name as the newer, standard type for +duration, the reference will refer this type as `OldDuration`. + Note that this is an "accurate" duration represented as seconds and nanoseconds and does not represent "nominal" components such as days or months. +When the `oldtime` feature is enabled, [`Duration`] is an alias for the +[`time::Duration`](https://docs.rs/time/0.1.40/time/struct.Duration.html) +type from v0.1 of the time crate. time v0.1 is deprecated, so new code +should disable the `oldtime` feature and use the `chrono::Duration` type +instead. The `oldtime` feature is enabled by default for backwards +compatibility, but future versions of Chrono are likely to remove the +feature entirely. + Chrono does not yet natively support the standard [`Duration`](https://doc.rust-lang.org/std/time/struct.Duration.html) type, but it will be supported in the future. diff --git a/src/lib.rs b/src/lib.rs index da25104e0c..9d66ae3249 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -64,15 +64,22 @@ //! //! ### Duration //! -//! Chrono currently uses -//! the [`time::Duration`](https://docs.rs/time/0.1.40/time/struct.Duration.html) type -//! from the `time` crate to represent the magnitude of a time span. -//! Since this has the same name as the newer, standard type for duration, -//! the reference will refer this type as `OldDuration`. +//! Chrono currently uses its own [`Duration`] type to represent the magnitude +//! of a time span. Since this has the same name as the newer, standard type for +//! duration, the reference will refer this type as `OldDuration`. +//! //! Note that this is an "accurate" duration represented as seconds and //! nanoseconds and does not represent "nominal" components such as days or //! months. //! +//! When the `oldtime` feature is enabled, [`Duration`] is an alias for the +//! [`time::Duration`](https://docs.rs/time/0.1.40/time/struct.Duration.html) +//! type from v0.1 of the time crate. time v0.1 is deprecated, so new code +//! should disable the `oldtime` feature and use the `chrono::Duration` type +//! instead. The `oldtime` feature is enabled by default for backwards +//! compatibility, but future versions of Chrono are likely to remove the +//! feature entirely. +//! //! Chrono does not yet natively support //! the standard [`Duration`](https://doc.rust-lang.org/std/time/struct.Duration.html) type, //! but it will be supported in the future.