time/
macros.rs

1//! Macros to construct statically known values.
2
3/// Construct a [`Date`](crate::Date) with a statically known value.
4///
5/// The resulting expression can be used in `const` or `static` declarations.
6///
7/// Three formats are supported: year-week-weekday, year-ordinal, and year-month-day.
8///
9/// ```rust
10/// # use time::{Date, Weekday::*, Month, macros::date};
11/// assert_eq!(
12///     date!(2020 - W 01 - 3),
13///     Date::from_iso_week_date(2020, 1, Wednesday)?
14/// );
15/// assert_eq!(date!(2020-001), Date::from_ordinal_date(2020, 1)?);
16/// assert_eq!(
17///     date!(2020-01-01),
18///     Date::from_calendar_date(2020, Month::January, 1)?
19/// );
20/// # Ok::<_, time::Error>(())
21/// ```
22pub use time_macros::date;
23/// Construct a [`PrimitiveDateTime`] or [`OffsetDateTime`] with a statically known value.
24///
25/// The resulting expression can be used in `const` or `static` declarations.
26///
27/// The syntax accepted by this macro is the same as [`date!`] and [`time!`], with an optional
28/// [`offset!`], all space-separated. If an [`offset!`] is provided, the resulting value will
29/// be an [`OffsetDateTime`]; otherwise it will be a [`PrimitiveDateTime`].
30///
31/// [`OffsetDateTime`]: crate::OffsetDateTime
32/// [`PrimitiveDateTime`]: crate::PrimitiveDateTime
33///
34/// ```rust
35/// # use time::{Date, Month, macros::datetime, UtcOffset};
36/// assert_eq!(
37///     datetime!(2020-01-01 0:00),
38///     Date::from_calendar_date(2020, Month::January, 1)?.midnight()
39/// );
40/// assert_eq!(
41///     datetime!(2020-01-01 0:00 UTC),
42///     Date::from_calendar_date(2020, Month::January, 1)?.midnight().assume_utc()
43/// );
44/// assert_eq!(
45///     datetime!(2020-01-01 0:00 -1),
46///     Date::from_calendar_date(2020, Month::January, 1)?.midnight()
47///         .assume_offset(UtcOffset::from_hms(-1, 0, 0)?)
48/// );
49/// # Ok::<_, time::Error>(())
50/// ```
51pub use time_macros::datetime;
52/// Equivalent of performing [`format_description::parse()`] at compile time.
53///
54/// Using the macro instead of the function results in a static slice rather than a
55/// [`Vec`](alloc::vec::Vec), such that it can be used in `#![no_alloc]` situations. For
56/// readability, you can use [`StaticFormatDescription`] as the type.
57///
58/// [`StaticFormatDescription`]: crate::format_description::StaticFormatDescription
59///
60/// The resulting expression can be used in `const` or `static` declarations, and implements
61/// the sealed traits required for both formatting and parsing.
62#[cfg_attr(feature = "alloc", doc = "```rust")]
63#[cfg_attr(not(feature = "alloc"), doc = "```rust,ignore")]
64/// # use time::{format_description, macros::format_description};
65/// assert_eq!(
66///     format_description!("[hour]:[minute]:[second]"),
67///     format_description::parse("[hour]:[minute]:[second]")?
68/// );
69/// # Ok::<_, time::Error>(())
70/// ```
71/// 
72/// The syntax accepted by this macro is the same as [`format_description::parse()`], which can
73/// be found in [the book](https://time-rs.github.io/book/api/format-description.html).
74///
75/// [`format_description::parse()`]: crate::format_description::parse()
76#[cfg(any(feature = "formatting", feature = "parsing"))]
77pub use time_macros::format_description;
78/// Construct a [`UtcOffset`](crate::UtcOffset) with a statically known value.
79///
80/// The resulting expression can be used in `const` or `static` declarations.
81///
82/// A sign and the hour must be provided; minutes and seconds default to zero. `UTC` (both
83/// uppercase and lowercase) is also allowed.
84///
85/// ```rust
86/// # use time::{UtcOffset, macros::offset};
87/// assert_eq!(offset!(UTC), UtcOffset::from_hms(0, 0, 0)?);
88/// assert_eq!(offset!(utc), UtcOffset::from_hms(0, 0, 0)?);
89/// assert_eq!(offset!(+0), UtcOffset::from_hms(0, 0, 0)?);
90/// assert_eq!(offset!(+1), UtcOffset::from_hms(1, 0, 0)?);
91/// assert_eq!(offset!(-1), UtcOffset::from_hms(-1, 0, 0)?);
92/// assert_eq!(offset!(+1:30), UtcOffset::from_hms(1, 30, 0)?);
93/// assert_eq!(offset!(-1:30), UtcOffset::from_hms(-1, -30, 0)?);
94/// assert_eq!(offset!(+1:30:59), UtcOffset::from_hms(1, 30, 59)?);
95/// assert_eq!(offset!(-1:30:59), UtcOffset::from_hms(-1, -30, -59)?);
96/// assert_eq!(offset!(+23:59:59), UtcOffset::from_hms(23, 59, 59)?);
97/// assert_eq!(offset!(-23:59:59), UtcOffset::from_hms(-23, -59, -59)?);
98/// # Ok::<_, time::Error>(())
99/// ```
100pub use time_macros::offset;
101/// Construct a [`Time`](crate::Time) with a statically known value.
102///
103/// The resulting expression can be used in `const` or `static` declarations.
104///
105/// Hours and minutes must be provided, while seconds defaults to zero. AM/PM is allowed
106/// (either uppercase or lowercase). Any number of subsecond digits may be provided (though any
107/// past nine will be discarded).
108///
109/// All components are validated at compile-time. An error will be raised if any value is
110/// invalid.
111///
112/// ```rust
113/// # use time::{Time, macros::time};
114/// assert_eq!(time!(0:00), Time::from_hms(0, 0, 0)?);
115/// assert_eq!(time!(1:02:03), Time::from_hms(1, 2, 3)?);
116/// assert_eq!(
117///     time!(1:02:03.004_005_006),
118///     Time::from_hms_nano(1, 2, 3, 4_005_006)?
119/// );
120/// assert_eq!(time!(12:00 am), Time::from_hms(0, 0, 0)?);
121/// assert_eq!(time!(1:02:03 am), Time::from_hms(1, 2, 3)?);
122/// assert_eq!(
123///     time!(1:02:03.004_005_006 am),
124///     Time::from_hms_nano(1, 2, 3, 4_005_006)?
125/// );
126/// assert_eq!(time!(12 pm), Time::from_hms(12, 0, 0)?);
127/// assert_eq!(time!(12:00 pm), Time::from_hms(12, 0, 0)?);
128/// assert_eq!(time!(1:02:03 pm), Time::from_hms(13, 2, 3)?);
129/// assert_eq!(
130///     time!(1:02:03.004_005_006 pm),
131///     Time::from_hms_nano(13, 2, 3, 4_005_006)?
132/// );
133/// # Ok::<_, time::Error>(())
134/// ```
135pub use time_macros::time;
136/// Construct a [`UtcDateTime`] with a statically known value.
137///
138/// The resulting expression can be used in `const` or `static` declarations.
139///
140/// The syntax accepted by this macro is the same as a space-separated [`date!`] and [`time!`].
141///
142/// [`UtcDateTime`]: crate::UtcDateTime
143///
144/// ```rust
145/// # use time::{Date, Month, macros::utc_datetime};
146/// assert_eq!(
147///     utc_datetime!(2020-01-01 0:00),
148///     Date::from_calendar_date(2020, Month::January, 1)?.midnight().as_utc()
149/// );
150/// # Ok::<_, time::Error>(())
151/// ```
152pub use time_macros::utc_datetime;
time/macros.rs

time/
macros.rs
