Add example for parsing into chrono::DateTime

- Add an example for parsing strings in different formats into chrono::DateTime
structs and chrono::Naive* structs
- Add links to chrono::*

See also: #324

src/basics.md

@@ -28,6 +28,7 @@
 | [Obtain backtrace of complex error scenarios][ex-error-chain-backtrace] | [![error-chain-badge]][error-chain] | [![cat-rust-patterns-badge]][cat-rust-patterns] |
 | [Measure elapsed time][ex-measure-elapsed-time] | [![std-badge]][std] | [![cat-time-badge]][cat-time] |
 | [Display formatted date and time][ex-format-datetime] | [![chrono-badge]][chrono] | [![cat-date-and-time-badge]][cat-date-and-time] |
+| [Parse string into DateTime struct][ex-parse-datetime] | [![chrono-badge]][chrono] | [![cat-date-and-time-badge]][cat-date-and-time] |
 
 [ex-std-read-lines]: #ex-std-read-lines
 <a name="ex-std-read-lines"></a>
@@ -1288,6 +1289,60 @@ fn main() {
 }
 ```
 
+[ex-parse-datetime]: #ex-parse-datetime
+<a name="ex-parse-datetime"></a>
+## Parse string into DateTime struct
+[![chrono-badge]][chrono] [![cat-date-and-time-badge]][cat-date-and-time]
+
+Parses a [`DateTime`] struct from strings representing the well-known formats
+[RFC 2822], [RFC 3339], and a custom format, using
+[`DateTime::parse_from_rfc2822`], [`DateTime::parse_from_rfc3339`], and
+[`DateTime::parse_from_str`] respectively.
+
+Escape sequences that are available for the [`DateTime::parse_from_str`] can be
+found at [`chrono::format::strftime`]. Note that the [`DateTime::parse_from_str`]
+requires that such a DateTime struct must be creatable that it uniquely
+identifies a date and a time. For parsing dates and times without timezones use
+[`NaiveDate`], [`NaiveTime`], and [`NaiveDateTime`].
+
+```rust
+extern crate chrono;
+# #[macro_use]
+# extern crate error_chain;
+#
+use chrono::{DateTime, NaiveDate, NaiveDateTime, NaiveTime};
+#
+# error_chain! {
+#     foreign_links {
+#         DateParse(chrono::format::ParseError);
+#     }
+# }
+
+fn run() -> Result<()> {
+    let rfc2822 = DateTime::parse_from_rfc2822("Tue, 1 Jul 2003 10:52:37 +0200")?;
+    println!("{}", rfc2822);
+
+    let rfc3339 = DateTime::parse_from_rfc3339("1996-12-19T16:39:57-08:00")?;
+    println!("{}", rfc3339);
+
+    let custom = DateTime::parse_from_str("5.8.1994 8:00 am +0000", "%d.%m.%Y %H:%M %P %z")?;
+    println!("{}", custom);
+
+    let time_only = NaiveTime::parse_from_str("23:56:04", "%H:%M:%S")?;
+    println!("{}", time_only);
+
+    let date_only = NaiveDate::parse_from_str("2015-09-05", "%Y-%m-%d")?;
+    println!("{}", date_only);
+
+    let no_timezone = NaiveDateTime::parse_from_str("2015-09-05 23:56:04", "%Y-%m-%d %H:%M:%S")?;
+    println!("{}", no_timezone);
+
+    Ok(())
+}
+#
+# quick_main!(run);
+```
+
 {{#include links.md}}
 
 <!-- API Reference -->
@@ -1298,10 +1353,18 @@ fn main() {
 [`BufRead`]: https://doc.rust-lang.org/std/io/trait.BufRead.html
 [`BufReader`]: https://doc.rust-lang.org/std/io/struct.BufReader.html
 [`chain_err`]: https://docs.rs/error-chain/*/error_chain/index.html#chaining-errors
+[`chrono::format::strftime`]: https://docs.rs/chrono/*/chrono/format/strftime/index.html
 [`Command`]: https://doc.rust-lang.org/std/process/struct.Command.html
 [`DateTime::format`]: https://docs.rs/chrono/*/chrono/struct.DateTime.html#method.format
+[`DateTime::format`]: https://docs.rs/chrono/*/chrono/struct.DateTime.html#method.format
+[`DateTime::parse_from_rfc2822`]: https://docs.rs/chrono/*/chrono/struct.DateTime.html#method.parse_from_rfc2822
+[`DateTime::parse_from_rfc3339`]: https://docs.rs/chrono/*/chrono/struct.DateTime.html#method.parse_from_rfc3339
+[`DateTime::parse_from_str`]: https://docs.rs/chrono/*/chrono/struct.DateTime.html#method.parse_from_str
+[`DateTime::to_rfc2822`]: https://docs.rs/chrono/*/chrono/struct.DateTime.html#method.to_rfc2822
 [`DateTime::to_rfc2822`]: https://docs.rs/chrono/*/chrono/struct.DateTime.html#method.to_rfc2822
 [`DateTime::to_rfc3339`]: https://docs.rs/chrono/*/chrono/struct.DateTime.html#method.to_rfc3339
+[`DateTime::to_rfc3339`]: https://docs.rs/chrono/*/chrono/struct.DateTime.html#method.to_rfc3339
+[`DateTime`]: https://docs.rs/chrono/*/chrono/struct.DateTime.html
 [`digest::Context`]: https://docs.rs/ring/*/ring/digest/struct.Context.html
 [`digest::Digest`]: https://docs.rs/ring/*/ring/digest/struct.Digest.html
 [`Display`]: https://doc.rust-lang.org/std/fmt/trait.Display.html
@@ -1316,6 +1379,9 @@ fn main() {
 [`Mmap::map`]: https://docs.rs/memmap/*/memmap/struct.Mmap.html#method.map
 [`Mutex`]: https://doc.rust-lang.org/std/sync/struct.Mutex.html
 [`MutexGuard`]: https://doc.rust-lang.org/std/sync/struct.MutexGuard.html
+[`NaiveDate`]: https://docs.rs/chrono/*/chrono/naive/struct.NaiveDate.html
+[`NaiveDateTime`]: https://docs.rs/chrono/*/chrono/naive/struct.NaiveDateTime.html
+[`NaiveTime`]: https://docs.rs/chrono/*/chrono/naive/struct.NaiveTime.html
 [`Normal`]: https://doc.rust-lang.org/rand/rand/distributions/normal/struct.Normal.html
 [`num_cpus::get`]: https://docs.rs/num_cpus/*/num_cpus/fn.get.html
 [`Output`]: https://doc.rust-lang.org/std/process/struct.Output.html

src/intro.md

@@ -46,6 +46,7 @@ community. It needs and welcomes help. For details see
 | [Obtain backtrace of complex error scenarios][ex-error-chain-backtrace] | [![error-chain-badge]][error-chain] | [![cat-rust-patterns-badge]][cat-rust-patterns] |
 | [Measure elapsed time][ex-measure-elapsed-time] | [![std-badge]][std] | [![cat-time-badge]][cat-time] |
 | [Display formatted date and time][ex-format-datetime] | [![chrono-badge]][chrono] | [![cat-date-and-time-badge]][cat-date-and-time] |
+| [Parse string into DateTime struct][ex-parse-datetime] | [![chrono-badge]][chrono] | [![cat-date-and-time-badge]][cat-date-and-time] |
 
 ## [Encoding](encoding.html)
 
@@ -193,8 +194,10 @@ community. It needs and welcomes help. For details see
 [ex-log-timestamp]: logging.html#ex-log-timestamp
 [ex-measure-elapsed-time]: basics.html#ex-measure-elapsed-time
 [ex-paginated-api]: net.html#ex-paginated-api
+[ex-parse-datetime]: basics.html#ex-parse-datetime
 [ex-parse-subprocess-input]: basics.html#ex-parse-subprocess-input
 [ex-parse-subprocess-output]: basics.html#ex-parse-subprocess-output
+[ex-parse-subprocess-output]: basics.html#ex-parse-subprocess-output
 [ex-pbkdf2]: basics.html#ex-pbkdf2
 [ex-percent-encode]: encoding.html#ex-percent-encode
 [ex-phone]: basics.html#ex-phone