time/format_description/
modifier.rs

Help
1//! Various modifiers for components.
2
3use core::num::NonZeroU16;
4
5// region: date modifiers
6/// Day of the month.
7#[non_exhaustive]
8#[derive(Debug, Clone, Copy, PartialEq, Eq)]
9pub struct Day {
10    /// The padding to obtain the minimum width.
11    pub padding: Padding,
12}
13
14/// The representation of a month.
15#[non_exhaustive]
16#[derive(Debug, Clone, Copy, PartialEq, Eq)]
17pub enum MonthRepr {
18    /// The number of the month (January is 1, December is 12).
19    Numerical,
20    /// The long form of the month name (e.g. "January").
21    Long,
22    /// The short form of the month name (e.g. "Jan").
23    Short,
24}
25
26/// Month of the year.
27#[non_exhaustive]
28#[derive(Debug, Clone, Copy, PartialEq, Eq)]
29pub struct Month {
30    /// The padding to obtain the minimum width.
31    pub padding: Padding,
32    /// What form of representation should be used?
33    pub repr: MonthRepr,
34    /// Is the value case sensitive when parsing?
35    pub case_sensitive: bool,
36}
37
38/// Ordinal day of the year.
39#[non_exhaustive]
40#[derive(Debug, Clone, Copy, PartialEq, Eq)]
41pub struct Ordinal {
42    /// The padding to obtain the minimum width.
43    pub padding: Padding,
44}
45
46/// The representation used for the day of the week.
47#[non_exhaustive]
48#[derive(Debug, Clone, Copy, PartialEq, Eq)]
49pub enum WeekdayRepr {
50    /// The short form of the weekday (e.g. "Mon").
51    Short,
52    /// The long form of the weekday (e.g. "Monday").
53    Long,
54    /// A numerical representation using Sunday as the first day of the week.
55    ///
56    /// Sunday is either 0 or 1, depending on the other modifier's value.
57    Sunday,
58    /// A numerical representation using Monday as the first day of the week.
59    ///
60    /// Monday is either 0 or 1, depending on the other modifier's value.
61    Monday,
62}
63
64/// Day of the week.
65#[non_exhaustive]
66#[derive(Debug, Clone, Copy, PartialEq, Eq)]
67pub struct Weekday {
68    /// What form of representation should be used?
69    pub repr: WeekdayRepr,
70    /// When using a numerical representation, should it be zero or one-indexed?
71    pub one_indexed: bool,
72    /// Is the value case sensitive when parsing?
73    pub case_sensitive: bool,
74}
75
76/// The representation used for the week number.
77#[non_exhaustive]
78#[derive(Debug, Clone, Copy, PartialEq, Eq)]
79pub enum WeekNumberRepr {
80    /// Week 1 is the week that contains January 4.
81    Iso,
82    /// Week 1 begins on the first Sunday of the calendar year.
83    Sunday,
84    /// Week 1 begins on the first Monday of the calendar year.
85    Monday,
86}
87
88/// Week within the year.
89#[non_exhaustive]
90#[derive(Debug, Clone, Copy, PartialEq, Eq)]
91pub struct WeekNumber {
92    /// The padding to obtain the minimum width.
93    pub padding: Padding,
94    /// What kind of representation should be used?
95    pub repr: WeekNumberRepr,
96}
97
98/// The representation used for a year value.
99#[non_exhaustive]
100#[derive(Debug, Clone, Copy, PartialEq, Eq)]
101pub enum YearRepr {
102    /// The full value of the year.
103    Full,
104    /// All digits except the last two. Includes the sign, if any.
105    Century,
106    /// Only the last two digits of the year.
107    LastTwo,
108}
109
110/// Year of the date.
111#[non_exhaustive]
112#[derive(Debug, Clone, Copy, PartialEq, Eq)]
113pub struct Year {
114    /// The padding to obtain the minimum width.
115    pub padding: Padding,
116    /// What kind of representation should be used?
117    pub repr: YearRepr,
118    /// Whether the value is based on the ISO week number or the Gregorian calendar.
119    pub iso_week_based: bool,
120    /// Whether the `+` sign is present when a positive year contains fewer than five digits.
121    pub sign_is_mandatory: bool,
122}
123// endregion date modifiers
124
125// region: time modifiers
126/// Hour of the day.
127#[non_exhaustive]
128#[derive(Debug, Clone, Copy, PartialEq, Eq)]
129pub struct Hour {
130    /// The padding to obtain the minimum width.
131    pub padding: Padding,
132    /// Is the hour displayed using a 12 or 24-hour clock?
133    pub is_12_hour_clock: bool,
134}
135
136/// Minute within the hour.
137#[non_exhaustive]
138#[derive(Debug, Clone, Copy, PartialEq, Eq)]
139pub struct Minute {
140    /// The padding to obtain the minimum width.
141    pub padding: Padding,
142}
143
144/// AM/PM part of the time.
145#[non_exhaustive]
146#[derive(Debug, Clone, Copy, PartialEq, Eq)]
147pub struct Period {
148    /// Is the period uppercase or lowercase?
149    pub is_uppercase: bool,
150    /// Is the value case sensitive when parsing?
151    ///
152    /// Note that when `false`, the `is_uppercase` field has no effect on parsing behavior.
153    pub case_sensitive: bool,
154}
155
156/// Second within the minute.
157#[non_exhaustive]
158#[derive(Debug, Clone, Copy, PartialEq, Eq)]
159pub struct Second {
160    /// The padding to obtain the minimum width.
161    pub padding: Padding,
162}
163
164/// The number of digits present in a subsecond representation.
165#[non_exhaustive]
166#[derive(Debug, Clone, Copy, PartialEq, Eq)]
167pub enum SubsecondDigits {
168    /// Exactly one digit.
169    One,
170    /// Exactly two digits.
171    Two,
172    /// Exactly three digits.
173    Three,
174    /// Exactly four digits.
175    Four,
176    /// Exactly five digits.
177    Five,
178    /// Exactly six digits.
179    Six,
180    /// Exactly seven digits.
181    Seven,
182    /// Exactly eight digits.
183    Eight,
184    /// Exactly nine digits.
185    Nine,
186    /// Any number of digits (up to nine) that is at least one. When formatting, the minimum digits
187    /// necessary will be used.
188    OneOrMore,
189}
190
191/// Subsecond within the second.
192#[non_exhaustive]
193#[derive(Debug, Clone, Copy, PartialEq, Eq)]
194pub struct Subsecond {
195    /// How many digits are present in the component?
196    pub digits: SubsecondDigits,
197}
198// endregion time modifiers
199
200// region: offset modifiers
201/// Hour of the UTC offset.
202#[non_exhaustive]
203#[derive(Debug, Clone, Copy, PartialEq, Eq)]
204pub struct OffsetHour {
205    /// Whether the `+` sign is present on positive values.
206    pub sign_is_mandatory: bool,
207    /// The padding to obtain the minimum width.
208    pub padding: Padding,
209}
210
211/// Minute within the hour of the UTC offset.
212#[non_exhaustive]
213#[derive(Debug, Clone, Copy, PartialEq, Eq)]
214pub struct OffsetMinute {
215    /// The padding to obtain the minimum width.
216    pub padding: Padding,
217}
218
219/// Second within the minute of the UTC offset.
220#[non_exhaustive]
221#[derive(Debug, Clone, Copy, PartialEq, Eq)]
222pub struct OffsetSecond {
223    /// The padding to obtain the minimum width.
224    pub padding: Padding,
225}
226// endregion offset modifiers
227
228/// Type of padding to ensure a minimum width.
229#[non_exhaustive]
230#[derive(Debug, Clone, Copy, PartialEq, Eq)]
231pub enum Padding {
232    /// A space character (` `) should be used as padding.
233    Space,
234    /// A zero character (`0`) should be used as padding.
235    Zero,
236    /// There is no padding. This can result in a width below the otherwise minimum number of
237    /// characters.
238    None,
239}
240
241/// Ignore some number of bytes.
242///
243/// This has no effect when formatting.
244#[non_exhaustive]
245#[derive(Debug, Clone, Copy, PartialEq, Eq)]
246pub struct Ignore {
247    /// The number of bytes to ignore.
248    pub count: NonZeroU16,
249}
250
251// Needed as `Default` is deliberately not implemented for `Ignore`. The number of bytes to ignore
252// must be explicitly provided.
253impl Ignore {
254    /// Create an instance of `Ignore` with the provided number of bytes to ignore.
255    pub const fn count(count: NonZeroU16) -> Self {
256        Self { count }
257    }
258}
259
260/// The precision of a Unix timestamp.
261#[non_exhaustive]
262#[derive(Debug, Clone, Copy, PartialEq, Eq)]
263pub enum UnixTimestampPrecision {
264    /// Seconds since the Unix epoch.
265    Second,
266    /// Milliseconds since the Unix epoch.
267    Millisecond,
268    /// Microseconds since the Unix epoch.
269    Microsecond,
270    /// Nanoseconds since the Unix epoch.
271    Nanosecond,
272}
273
274/// A Unix timestamp.
275#[non_exhaustive]
276#[derive(Debug, Clone, Copy, PartialEq, Eq)]
277pub struct UnixTimestamp {
278    /// The precision of the timestamp.
279    pub precision: UnixTimestampPrecision,
280    /// Whether the `+` sign must be present for a non-negative timestamp.
281    pub sign_is_mandatory: bool,
282}
283
284/// The end of input.
285///
286/// There is currently not customization for this modifier.
287#[non_exhaustive]
288#[derive(Debug, Clone, Copy, PartialEq, Eq)]
289pub struct End;
290
291/// Generate the provided code if and only if `pub` is present.
292macro_rules! if_pub {
293    (pub $(#[$attr:meta])*; $($x:tt)*) => {
294        $(#[$attr])*
295        ///
296        /// This function exists since [`Default::default()`] cannot be used in a `const` context.
297        /// It may be removed once that becomes possible. As the [`Default`] trait is in the
298        /// prelude, removing this function in the future will not cause any resolution failures for
299        /// the overwhelming majority of users; only users who use `#![no_implicit_prelude]` will be
300        /// affected. As such it will not be considered a breaking change.
301        $($x)*
302    };
303    ($($_:tt)*) => {};
304}
305
306/// Implement `Default` for the given type. This also generates an inherent implementation of a
307/// `default` method that is `const fn`, permitting the default value to be used in const contexts.
308// Every modifier should use this macro rather than a derived `Default`.
309macro_rules! impl_const_default {
310    ($($(#[$doc:meta])* $(@$pub:ident)? $type:ty => $default:expr;)*) => {$(
311        impl $type {
312            if_pub! {
313                $($pub)?
314                $(#[$doc])*;
315                pub const fn default() -> Self {
316                    $default
317                }
318            }
319        }
320
321        $(#[$doc])*
322        impl Default for $type {
323            fn default() -> Self {
324                $default
325            }
326        }
327    )*};
328}
329
330impl_const_default! {
331    /// Creates a modifier that indicates the value is [padded with zeroes](Padding::Zero).
332    @pub Day => Self { padding: Padding::Zero };
333    /// Creates a modifier that indicates the value uses the
334    /// [`Numerical`](Self::Numerical) representation.
335    MonthRepr => Self::Numerical;
336    /// Creates an instance of this type that indicates the value uses the
337    /// [`Numerical`](MonthRepr::Numerical) representation, is [padded with zeroes](Padding::Zero),
338    /// and is case-sensitive when parsing.
339    @pub Month => Self {
340        padding: Padding::Zero,
341        repr: MonthRepr::Numerical,
342        case_sensitive: true,
343    };
344    /// Creates a modifier that indicates the value is [padded with zeroes](Padding::Zero).
345    @pub Ordinal => Self { padding: Padding::Zero };
346    /// Creates a modifier that indicates the value uses the [`Long`](Self::Long) representation.
347    WeekdayRepr => Self::Long;
348    /// Creates a modifier that indicates the value uses the [`Long`](WeekdayRepr::Long)
349    /// representation and is case-sensitive when parsing. If the representation is changed to a
350    /// numerical one, the instance defaults to one-based indexing.
351    @pub Weekday => Self {
352        repr: WeekdayRepr::Long,
353        one_indexed: true,
354        case_sensitive: true,
355    };
356    /// Creates a modifier that indicates that the value uses the [`Iso`](Self::Iso) representation.
357    WeekNumberRepr => Self::Iso;
358    /// Creates a modifier that indicates that the value is [padded with zeroes](Padding::Zero)
359            /// and uses the [`Iso`](WeekNumberRepr::Iso) representation.
360    @pub WeekNumber => Self {
361        padding: Padding::Zero,
362        repr: WeekNumberRepr::Iso,
363    };
364    /// Creates a modifier that indicates the value uses the [`Full`](Self::Full) representation.
365    YearRepr => Self::Full;
366    /// Creates a modifier that indicates the value uses the [`Full`](YearRepr::Full)
367    /// representation, is [padded with zeroes](Padding::Zero), uses the Gregorian calendar as its
368    /// base, and only includes the year's sign if necessary.
369    @pub Year => Self {
370        padding: Padding::Zero,
371        repr: YearRepr::Full,
372        iso_week_based: false,
373        sign_is_mandatory: false,
374    };
375    /// Creates a modifier that indicates the value is [padded with zeroes](Padding::Zero) and
376    /// has the 24-hour representation.
377    @pub Hour => Self {
378        padding: Padding::Zero,
379        is_12_hour_clock: false,
380    };
381    /// Creates a modifier that indicates the value is [padded with zeroes](Padding::Zero).
382    @pub Minute => Self { padding: Padding::Zero };
383    /// Creates a modifier that indicates the value uses the upper-case representation and is
384    /// case-sensitive when parsing.
385    @pub Period => Self {
386        is_uppercase: true,
387        case_sensitive: true,
388    };
389    /// Creates a modifier that indicates the value is [padded with zeroes](Padding::Zero).
390    @pub Second => Self { padding: Padding::Zero };
391    /// Creates a modifier that indicates the stringified value contains [one or more
392    /// digits](Self::OneOrMore).
393    SubsecondDigits => Self::OneOrMore;
394    /// Creates a modifier that indicates the stringified value contains [one or more
395    /// digits](SubsecondDigits::OneOrMore).
396    @pub Subsecond => Self { digits: SubsecondDigits::OneOrMore };
397    /// Creates a modifier that indicates the value only uses a sign for negative values and is
398    /// [padded with zeroes](Padding::Zero).
399    @pub OffsetHour => Self {
400        sign_is_mandatory: false,
401        padding: Padding::Zero,
402    };
403    /// Creates a modifier that indicates the value is [padded with zeroes](Padding::Zero).
404    @pub OffsetMinute => Self { padding: Padding::Zero };
405    /// Creates a modifier that indicates the value is [padded with zeroes](Padding::Zero).
406    @pub OffsetSecond => Self { padding: Padding::Zero };
407    /// Creates a modifier that indicates the value is [padded with zeroes](Self::Zero).
408    Padding => Self::Zero;
409    /// Creates a modifier that indicates the value represents the [number of seconds](Self::Second)
410    /// since the Unix epoch.
411    UnixTimestampPrecision => Self::Second;
412    /// Creates a modifier that indicates the value represents the [number of
413    /// seconds](UnixTimestampPrecision::Second) since the Unix epoch. The sign is not mandatory.
414    @pub UnixTimestamp => Self {
415        precision: UnixTimestampPrecision::Second,
416        sign_is_mandatory: false,
417    };
418    /// Creates a modifier used to represent the end of input.
419    @pub End => End;
420}
time/format_description/modifier.rs

time/format_description/
modifier.rs
