From 3f71acb4e9ca32d8864fd4a38a9b5ddd60eba279 Mon Sep 17 00:00:00 2001 From: Hugo Elhaj-Lahsen Date: Wed, 10 Aug 2022 04:31:58 +0200 Subject: [PATCH] Add create and parse how-to guide (#4) --- src/SUMMARY.md | 7 ++- src/how-to/create-dates.md | 94 ++++++++++++++++++++++++++++++++++++++ src/how-to/parse-dates.md | 75 ++++++++++++++++++++++++++++++ 3 files changed, 172 insertions(+), 4 deletions(-) create mode 100644 src/how-to/create-dates.md create mode 100644 src/how-to/parse-dates.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 9e38b5d..95c61c4 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -2,11 +2,10 @@ - [Overview](./index.md) -# 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 diff --git a/src/how-to/create-dates.md b/src/how-to/create-dates.md new file mode 100644 index 0000000..33033e5 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/src/how-to/parse-dates.md b/src/how-to/parse-dates.md new file mode 100644 index 0000000..4aa8f85 --- /dev/null +++ b/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/ \ No newline at end of file