vendor/time/src/format_description/modifier.rs

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