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