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}
421