Add create and parse how-to guide

src/SUMMARY.md

@@ -2,11 +2,10 @@
 
 - [Overview](./index.md) <!-- would be nice to have a custom index here -->
 
-# How-to guide
+# How-to guides
 
-- [What Time can do](./intro/what-time-can-do.md)
-- [What Time can't do](./intro/what-time-cant-do.md)
-- [Limitations and alternatives](./intro/limitations-and-alternatives.md)
+- [Create dates and times](./how-to/create-dates.md)
+- [Parse dates](./how-to/parse-dates.md)
 
 # Technical reference
 

src/how-to/create-dates.md

@@ -0,0 +1,94 @@
+# Create dates and times
+
+`time` provides a [`const`][const]-ready API. All functions here are `const`: values can be computed
+at compile-time if you pass constants, with no difference if used at runtime.
+
+For convenience, macros are provided with [feature `macros`][feature-macros]. They let us restrict
+parameters further, avoiding the need to `unwrap()` at the cost of compilation time.
+
+## Creating [`Date`][Date]s
+
+From a constant value, with [feature `macros`][feature-macros]:
+
+```rust
+use time::macros::date;
+
+let _ = date!(2022-01-02);
+```
+
+From a calendar date:
+```rust
+use time::{Date, Month};
+
+let _ = Date::from_calendar_date(2022, Month::January, 2).unwrap();
+```
+
+## Creating [`PrimitiveDateTime`][PrimitiveDateTime]s
+
+A `PrimitiveDateTime` is both a date and a time. We can create them directly:
+
+```rust
+use time::macros::datetime;
+
+let _ = datetime!(2022-01-02 11:12:13.123_456_789);
+```
+
+or use an existing `Date`:
+
+```rust
+use time::macros::{date, time};
+use time::Time;
+
+let date = date!(2022-01-02);
+
+// A date with 00:00:00 time
+let _ = date.midnight();
+// You can also provide a desired time...
+let _ = date.with_hms(11, 12, 13).unwrap();
+// or pass an existing `Time`
+let _ = date.with_time(Time::from_hms_nano(11, 12, 13, 123_456_789).unwrap());
+// with macros:
+let _ = date.with_time(time!(11:12:13.123_456_789));
+```
+
+## Creating [`OffsetDateTime`][OffsetDateTime]s
+
+An `OffsetDateTime` is a date, time and [UTC offset][UTC offset, Wikipedia]
+. Use it if you deal with timezones:
+
+```rust
+use time::macros::datetime;
+
+// When we pass an offset at the end to `datetime!`, it will return an 
+// `OffsetDateTime` instead of an `PrimitiveDateTime`
+let _ = datetime!(2022-01-02 11:12:13 UTC);
+// With a positive offset:
+let _ = datetime!(2022-01-02 11:12:13 +1);
+// and a negative offset:
+let _ = datetime!(2022-01-02 11:12:13.123_456_789 -2:34:56);
+```
+
+or, using an existing `PrimitiveDateTime`, with 
+[`UtcOffset`][UtcOffset]:
+
+```rust
+use time::macros::{datetime, offset};
+use time::UtcOffset;
+
+let dt = datetime!(2022-01-02 11:12:13);
+
+// With UTC:
+let _ = dt.assume_utc();
+// or with another offset:
+let _ = dt.assume_offset(UtcOffset::from_hms(1, 2, 3));
+// with macros:
+let _ = dt.assume_offset(offset!(-11));
+```
+
+[const]: https://doc.rust-lang.org/std/keyword.const.html
+[feature-macros]: https://docs.rs/time/latest/time/#feature-flags
+[Date]: https://docs.rs/time/latest/time/struct.Date.html
+[PrimitiveDateTime]: https://docs.rs/time/latest/time/struct.PrimitiveDateTime.html
+[OffsetDateTime]: https://docs.rs/time/latest/time/struct.OffsetDateTime.html
+[UTC offset, Wikipedia]: https://en.wikipedia.org/wiki/UTC_offset
+[UtcOffset]: https://docs.rs/time/latest/time/struct.UtcOffset.html

src/how-to/parse-dates.md

@@ -0,0 +1,75 @@
+# Parse dates
+
+`time` has can parse datetimes from strings, in any given format.
+
+## Parse a date from a string
+
+1. Enable [feature `parsing`][feature-parsing].
+
+2. Using the common ISO 8601 format, via the [`Iso8601`][Iso8601] format description:
+
+```rust
+use time::format_description::well_known::Iso8601;
+use time::PrimitiveDateTime;
+
+let date = PrimitiveDateTime::parse("2022-01-02T11:12:13", &Iso8601::DEFAULT)
+    .unwrap();
+```
+
+## Parsing custom formats
+
+`time` supports a few common formats, that we call [well-known formats][well-known]. We support 
+arbitrary formats as well.
+
+1. Enable [feature `macros` and `parsing`](https://docs.rs/time/latest/time/#feature-flags). 
+   `macros` are used to call `format_description!`, but you can also call 
+   [the equivalent function](https://docs.rs/time/latest/time/format_description/fn.parse.html).
+
+2. Create a format and parse:
+
+```rust
+use time::macros::format_description;
+use time::Time;
+
+let my_format = format_description!("h=[hour],m=[minute],s=[second]");
+let time = Time::parse("h=11,m=12,s=13", &my_format).unwrap();
+```
+
+[Reference for format descriptions can be found here](../api/format-description.md).
+
+## Parsing into structs with serde
+
+For convenience, you can use Serde with `time`.
+
+1. Enable [feature `serde-well-known`][serde-well-known].
+
+2. Create a struct and parse from a format, eg. JSON using [`serde-json`][serde-json]:
+
+```rust
+use time::macros::format_description;
+use time::{OffsetDateTime, Time};
+use serde::{Deserialize};
+
+#[derive(Deserialize)]
+struct Notification {
+    message: String,
+    #[serde(with = "time::serde::iso8601")]
+    timestamp: OffsetDateTime,
+}
+
+fn main() {
+    let input = r#"{
+      "message": "foo",
+      "timestamp": "2022-01-02T11:12:13Z"
+    }"#;
+
+    let notification: Notification = serde_json::from_str(input).unwrap();
+    println!("{:?}", notification.timestamp);
+}
+```
+
+[feature-parsing]: https://docs.rs/time/latest/time/#feature-flags
+[Iso8601]: https://docs.rs/time/latest/time/format_description/well_known/struct.Iso8601.html
+[well-known]: https://docs.rs/time/latest/time/format_description/well_known/index.html
+[feature-serde-well-known]: https://docs.rs/time/latest/time/#feature-flags
+[serde-json]: https://docs.rs/serde_json/latest/serde_json/