From 6a9490522e77da1d7041ec99054f75363b7fcca5 Mon Sep 17 00:00:00 2001 From: Kang Seonghoon Date: Thu, 19 Feb 2015 05:08:00 +0900 Subject: [PATCH] updated docs for RFC2822/3339 and added ChangeLog. --- AUTHORS.txt | 1 + CHANGELOG.md | 145 +++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 18 +++++-- src/lib.rs | 15 ++++-- 4 files changed, 170 insertions(+), 9 deletions(-) create mode 100644 CHANGELOG.md diff --git a/AUTHORS.txt b/AUTHORS.txt index 9cff58b..00739f1 100644 --- a/AUTHORS.txt +++ b/AUTHORS.txt @@ -4,6 +4,7 @@ and also the following people (in ascending order): Colin Ray David Ross Eunchong Yu +John Nagle Ken Tossell Steve Klabnik klutzy diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..d1e7e7e --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,145 @@ +ChangeLog for Chrono +==================== + +This documents all notable changes to [Chrono](https://github.com/lifthrasiir/rust-chrono). + +Chrono obeys the principle of [Semantic Versioning](http://semver.org/). + +There were/are numerous minor versions before 1.0 due to the language changes. +Versions with only mechnical changes will be omitted from the following list. + +## 0.2.0 (UNRELEASED) + +### Added + +- `Offset` is splitted into `TimeZone` (constructor) and `Offset` (storage) types. + You would normally see only the former, as the latter is mostly an implementation detail. + Most importantly, `Local` now can be used to directly construct timezone-aware values. + + Some types (currently, `UTC` and `FixedOffset`) are both `TimeZone` and `Offset`, + but others aren't (e.g. `Local` is not what is being stored to each `DateTime` values). + +- `LocalResult::map` convenience method has been added. + +- `TimeZone` now allows a construction of `DateTime` values from UNIX timestamp, + via `timestamp` and `timestamp_opt` methods. + +- `TimeZone` now also has a method for parsing `DateTime`, namely `datetime_from_str`. + +- The following methods have been added to all date and time types: + + - `checked_add` + - `checked_sub` + - `format_with_items` + +- The following methods have been added to all timezone-aware types: + + - `timezone` + - `with_timezone` + - `naive_utc` + - `naive_local` + +- `parse_from_str` method has been added to all naive types and `DateTime`. + +- All naive types and instances of `DateTime` with time zones `UTC`, `Local` and `FixedOffset` + implement the `FromStr` trait. They parse what `std::fmt::Debug` would print. + +- `chrono::format` has been greatly rewritten. + + - The formatting syntax parser is modular now, available at `chrono::format::strftime`. + + - The parser and resolution algorithm is also modular, the former is available at + `chrono::format::parse` while the latter is available at `chrono::format::parsed`. + + - Explicit support for RFC 2822 and 3339 syntaxes is landed. + + - There is a minor formatting difference with atypical values, + e.g. for years not between 1 BCE and 9999 CE. + +### Changed + +- Most uses of `Offset` are converted to `TimeZone`. + In fact, *all* user-facing code is expected to be `Offset`-free. + +- `[Naive]DateTime::*num_seconds_from_unix_epoch*` methods have been renamed to + simply `timestamp` or `from_timestamp*`. The original names have been deprecated. + +### Removed + +- `Time` has been removed. This also prompts a related set of methods in `TimeZone`. + + This is in principle possible, but in practice has seen a little use + because it can only be meaningfully constructed via an existing `DateTime` value. + This made many operations to `Time` unintuitive or ambiguous, + so we simply let it go. + + In the case that `Time` is really required, one can use a simpler `NaiveTime`. + `NaiveTime` and `NaiveDate` can be freely combined and splitted, + and `TimeZone::from_{local,utc}_datetime` can be used to convert from/to the local time. + +- `with_offset` method has been removed. Use `with_timezone` method instead. + (This is not deprecated since it is an integral part of offset reform.) + +## 0.1.14 (2015-01-10) + +### Added + +- Added a missing `std::fmt::String` impl for `Local`. + +## 0.1.13 (2015-01-10) + +### Changed + +- Most types now implement both `std::fmt::Show` and `std::fmt::String`, + with the former used for the stricter output and the latter used for more casual output. + +### Removed + +- `Offset::name` has been replaced by a `std::fmt::String` implementation to `Offset`. + +## 0.1.12 (2015-01-08) + +### Removed + +- `Duration + T` no longer works due to the updated impl reachability rules. + Use `T + Duration` as a workaround. + +## 0.1.4 (2014-12-13) + +### Fixed + +- Fixed a bug that `Date::and_*` methods with an offset that can change the date are + off by one day. + +## 0.1.3 (2014-11-28) + +### Added + +- `{Date,Time,DateTime}::with_offset` methods have been added. + +- `LocalResult` now implements a common set of traits. + +- `LocalResult::and_*` methods have been added. + They are useful for safely chaining `LocalResult>` methods + to make `LocalResult>`. + +### Changed + +- `Offset::name` now returns `SendStr`. + +- `{Date,Time} - Duration` overloadings are now allowed. + +## 0.1.2 (2014-11-24) + +### Added + +- `Duration + Date` overloading is now allowed. + +### Changed + +- Chrono no longer needs `num` dependency. + +## 0.1.0 (2014-11-20) + +The initial version that was available to `crates.io`. + diff --git a/README.md b/README.md index e4bf896..99c319b 100644 --- a/README.md +++ b/README.md @@ -138,7 +138,9 @@ assert_eq!(UTC.ymd(1970, 1, 1).and_hms(0, 0, 0) - Duration::seconds(1_000_000_00 Formatting is done via the `format` method, which format is equivalent to the familiar `strftime` format. (See the `format::strftime` module documentation for full syntax.) + The default `to_string` method and `{:?}` specifier also give a reasonable representation. +Chrono also provides `to_rfc{2822,3339}` methods for well-known formats. ~~~~ {.rust} use chrono::*; @@ -149,6 +151,8 @@ assert_eq!(dt.format("%a %b %e %T %Y").to_string(), "Fri Nov 28 12:00:09 2014"); assert_eq!(dt.format("%a %b %e %T %Y").to_string(), dt.format("%c").to_string()); assert_eq!(dt.to_string(), "2014-11-28 12:00:09 UTC"); +assert_eq!(dt.to_rfc2822(), "Fri, 28 Nov 2014 12:00:09 +0000"); +assert_eq!(dt.to_rfc3339(), "2014-11-28T12:00:09+00:00"); assert_eq!(format!("{:?}", dt), "2014-11-28T12:00:09Z"); ~~~~ @@ -163,6 +167,7 @@ Parsing can be done with three methods: returns `DateTime`. This should be used when the offset is a part of input and the caller cannot guess that. It *cannot* be used when the offset can be missing. + `DateTime::parse_from_rfc{2822,3339}` are similar but for well-known formats. 3. `Offset::datetime_from_str` is similar but returns `DateTime` of given offset. When the explicit offset is missing from the input, it simply uses given offset. @@ -182,12 +187,14 @@ assert_eq!("2014-11-28T21:00:09+09:00".parse::>(), Ok(dt.clone())) assert_eq!("2014-11-28T21:00:09+09:00".parse::>(), Ok(fixed_dt.clone())); // method 2 -assert_eq!(UTC.datetime_from_str("2014-11-28 12:00:09", "%Y-%m-%d %H:%M:%S"), Ok(dt.clone())); -assert_eq!(UTC.datetime_from_str("Fri Nov 28 12:00:09 2014", "%a %b %e %T %Y"), Ok(dt.clone())); - -// method 3 assert_eq!(DateTime::parse_from_str("2014-11-28 21:00:09 +09:00", "%Y-%m-%d %H:%M:%S %z"), Ok(fixed_dt.clone())); +assert_eq!(DateTime::parse_from_rfc2822("Fri, 28 Nov 2014 21:00:09 +0900"), Ok(fixed_dt.clone())); +assert_eq!(DateTime::parse_from_rfc3339("2014-11-28T21:00:09+09:00"), Ok(fixed_dt.clone())); + +// method 3 +assert_eq!(UTC.datetime_from_str("2014-11-28 12:00:09", "%Y-%m-%d %H:%M:%S"), Ok(dt.clone())); +assert_eq!(UTC.datetime_from_str("Fri Nov 28 12:00:09 2014", "%a %b %e %T %Y"), Ok(dt.clone())); // oops, the year is missing! assert!(UTC.datetime_from_str("Fri Nov 28 12:00:09", "%a %b %e %T %Y").is_err()); @@ -212,7 +219,8 @@ assert_eq!(Local::today(), Local::now().date()); assert_eq!(UTC.ymd(2014, 11, 28).weekday(), Weekday::Fri); assert_eq!(UTC.ymd_opt(2014, 11, 31), LocalResult::None); -assert_eq!(UTC.hms_milli(7, 8, 9, 10).format("%H%M%S").to_string(), "070809"); +assert_eq!(UTC.ymd(2014, 11, 28).and_hms_milli(7, 8, 9, 10).format("%H%M%S").to_string(), + "070809"); ~~~~ `DateTime` has two methods, `date` and `time`, diff --git a/src/lib.rs b/src/lib.rs index a87736b..57d8cdb 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -139,7 +139,9 @@ assert_eq!(UTC.ymd(1970, 1, 1).and_hms(0, 0, 0) - Duration::seconds(1_000_000_00 Formatting is done via the `format` method, which format is equivalent to the familiar `strftime` format. (See the `format::strftime` module documentation for full syntax.) + The default `to_string` method and `{:?}` specifier also give a reasonable representation. +Chrono also provides `to_rfc{2822,3339}` methods for well-known formats. ~~~~ {.rust} use chrono::*; @@ -150,6 +152,8 @@ assert_eq!(dt.format("%a %b %e %T %Y").to_string(), "Fri Nov 28 12:00:09 2014"); assert_eq!(dt.format("%a %b %e %T %Y").to_string(), dt.format("%c").to_string()); assert_eq!(dt.to_string(), "2014-11-28 12:00:09 UTC"); +assert_eq!(dt.to_rfc2822(), "Fri, 28 Nov 2014 12:00:09 +0000"); +assert_eq!(dt.to_rfc3339(), "2014-11-28T12:00:09+00:00"); assert_eq!(format!("{:?}", dt), "2014-11-28T12:00:09Z"); ~~~~ @@ -164,6 +168,7 @@ Parsing can be done with three methods: returns `DateTime`. This should be used when the offset is a part of input and the caller cannot guess that. It *cannot* be used when the offset can be missing. + `DateTime::parse_from_rfc{2822,3339}` are similar but for well-known formats. 3. `Offset::datetime_from_str` is similar but returns `DateTime` of given offset. When the explicit offset is missing from the input, it simply uses given offset. @@ -183,12 +188,14 @@ assert_eq!("2014-11-28T21:00:09+09:00".parse::>(), Ok(dt.clone())) assert_eq!("2014-11-28T21:00:09+09:00".parse::>(), Ok(fixed_dt.clone())); // method 2 -assert_eq!(UTC.datetime_from_str("2014-11-28 12:00:09", "%Y-%m-%d %H:%M:%S"), Ok(dt.clone())); -assert_eq!(UTC.datetime_from_str("Fri Nov 28 12:00:09 2014", "%a %b %e %T %Y"), Ok(dt.clone())); - -// method 3 assert_eq!(DateTime::parse_from_str("2014-11-28 21:00:09 +09:00", "%Y-%m-%d %H:%M:%S %z"), Ok(fixed_dt.clone())); +assert_eq!(DateTime::parse_from_rfc2822("Fri, 28 Nov 2014 21:00:09 +0900"), Ok(fixed_dt.clone())); +assert_eq!(DateTime::parse_from_rfc3339("2014-11-28T21:00:09+09:00"), Ok(fixed_dt.clone())); + +// method 3 +assert_eq!(UTC.datetime_from_str("2014-11-28 12:00:09", "%Y-%m-%d %H:%M:%S"), Ok(dt.clone())); +assert_eq!(UTC.datetime_from_str("Fri Nov 28 12:00:09 2014", "%a %b %e %T %Y"), Ok(dt.clone())); // oops, the year is missing! assert!(UTC.datetime_from_str("Fri Nov 28 12:00:09", "%a %b %e %T %Y").is_err());