updated docs for RFC2822/3339 and added ChangeLog.
This commit is contained in:
Kang Seonghoon
parent
30322bbc89
commit
6a9490522e
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
||||
18
README.md
18
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`,
|
||||
|
|
|
|||
15
src/lib.rs
15
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());
|
||||
|
|
|
|||
Loading…
Reference in New Issue