updated docs for RFC2822/3339 and added ChangeLog.

AUTHORS.txt

@@ -4,6 +4,7 @@ and also the following people (in ascending order):
 Colin Ray <r.colinray@gmail.com>
 David Ross <daboross@daboross.net>
 Eunchong Yu <kroisse@gmail.com>
+John Nagle <nagle@sitetruth.com>
 Ken Tossell <ken@tossell.net>
 Steve Klabnik <steve@steveklabnik.com>
 klutzy <klutzytheklutzy@gmail.com>

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<FixedOffset>`.
+
+- 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<Date<Off>>` methods
+  to make `LocalResult<DateTime<Off>>`.
+
+### 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`.
+

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<FixedOffset>`.
    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::<DateTime<UTC>>(), Ok(dt.clone()))
 assert_eq!("2014-11-28T21:00:09+09:00".parse::<DateTime<FixedOffset>>(), 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`,

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<FixedOffset>`.
    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::<DateTime<UTC>>(), Ok(dt.clone()))
 assert_eq!("2014-11-28T21:00:09+09:00".parse::<DateTime<FixedOffset>>(), 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());