1// This is a part of Chrono.
2// See README.md and LICENSE.txt for details.
3
4//! Formatting (and parsing) utilities for date and time.
5//!
6//! This module provides the common types and routines to implement,
7//! for example, [`DateTime::format`](../struct.DateTime.html#method.format) or
8//! [`DateTime::parse_from_str`](../struct.DateTime.html#method.parse_from_str) methods.
9//! For most cases you should use these high-level interfaces.
10//!
11//! Internally the formatting and parsing shares the same abstract **formatting items**,
12//! which are just an [`Iterator`](https://doc.rust-lang.org/std/iter/trait.Iterator.html) of
13//! the [`Item`](./enum.Item.html) type.
14//! They are generated from more readable **format strings**;
15//! currently Chrono supports a built-in syntax closely resembling
16//! C's `strftime` format. The available options can be found [here](./strftime/index.html).
17//!
18//! # Example
19//! ```
20//! # #[cfg(feature = "alloc")] {
21//! use chrono::{NaiveDateTime, TimeZone, Utc};
22//!
23//! let date_time = Utc.with_ymd_and_hms(2020, 11, 10, 0, 1, 32).unwrap();
24//!
25//! let formatted = format!("{}", date_time.format("%Y-%m-%d %H:%M:%S"));
26//! assert_eq!(formatted, "2020-11-10 00:01:32");
27//!
28//! let parsed = NaiveDateTime::parse_from_str(&formatted, "%Y-%m-%d %H:%M:%S")?.and_utc();
29//! assert_eq!(parsed, date_time);
30//! # }
31//! # Ok::<(), chrono::ParseError>(())
32//! ```
33
34#[cfg(all(feature = "alloc", not(feature = "std"), not(test)))]
35use alloc::boxed::Box;
36use core::fmt;
37use core::str::FromStr;
38#[cfg(feature = "std")]
39use std::error::Error;
40
41use crate::{Month, ParseMonthError, ParseWeekdayError, Weekday};
42
43mod formatting;
44mod parsed;
45
46// due to the size of parsing routines, they are in separate modules.
47mod parse;
48pub(crate) mod scan;
49
50pub mod strftime;
51
52#[allow(unused)]
53// TODO: remove '#[allow(unused)]' once we use this module for parsing or something else that does
54// not require `alloc`.
55pub(crate) mod locales;
56
57pub use formatting::SecondsFormat;
58pub(crate) use formatting::write_hundreds;
59#[cfg(feature = "alloc")]
60pub(crate) use formatting::write_rfc2822;
61#[cfg(any(feature = "alloc", feature = "serde"))]
62pub(crate) use formatting::write_rfc3339;
63#[cfg(feature = "alloc")]
64#[allow(deprecated)]
65pub use formatting::{DelayedFormat, format, format_item};
66#[cfg(feature = "unstable-locales")]
67pub use locales::Locale;
68pub(crate) use parse::parse_rfc3339;
69pub use parse::{parse, parse_and_remainder};
70pub use parsed::Parsed;
71pub use strftime::StrftimeItems;
72
73/// An uninhabited type used for `InternalNumeric` and `InternalFixed` below.
74#[derive(Clone, PartialEq, Eq, Hash)]
75enum Void {}
76
77/// Padding characters for numeric items.
78#[derive(Copy, Clone, PartialEq, Eq, Debug, Hash)]
79pub enum Pad {
80 /// No padding.
81 None,
82 /// Zero (`0`) padding.
83 Zero,
84 /// Space padding.
85 Space,
86}
87
88/// Numeric item types.
89/// They have associated formatting width (FW) and parsing width (PW).
90///
91/// The **formatting width** is the minimal width to be formatted.
92/// If the number is too short, and the padding is not [`Pad::None`](./enum.Pad.html#variant.None),
93/// then it is left-padded.
94/// If the number is too long or (in some cases) negative, it is printed as is.
95///
96/// The **parsing width** is the maximal width to be scanned.
97/// The parser only tries to consume from one to given number of digits (greedily).
98/// It also trims the preceding whitespace if any.
99/// It cannot parse the negative number, so some date and time cannot be formatted then
100/// parsed with the same formatting items.
101#[non_exhaustive]
102#[derive(Clone, PartialEq, Eq, Debug, Hash)]
103pub enum Numeric {
104 /// Full Gregorian year (FW=4, PW=∞).
105 /// May accept years before 1 BCE or after 9999 CE, given an initial sign (+/-).
106 Year,
107 /// Gregorian year divided by 100 (century number; FW=PW=2). Implies the non-negative year.
108 YearDiv100,
109 /// Gregorian year modulo 100 (FW=PW=2). Cannot be negative.
110 YearMod100,
111 /// Year in the ISO week date (FW=4, PW=∞).
112 /// May accept years before 1 BCE or after 9999 CE, given an initial sign.
113 IsoYear,
114 /// Year in the ISO week date, divided by 100 (FW=PW=2). Implies the non-negative year.
115 IsoYearDiv100,
116 /// Year in the ISO week date, modulo 100 (FW=PW=2). Cannot be negative.
117 IsoYearMod100,
118 /// Quarter (FW=PW=1).
119 Quarter,
120 /// Month (FW=PW=2).
121 Month,
122 /// Day of the month (FW=PW=2).
123 Day,
124 /// Week number, where the week 1 starts at the first Sunday of January (FW=PW=2).
125 WeekFromSun,
126 /// Week number, where the week 1 starts at the first Monday of January (FW=PW=2).
127 WeekFromMon,
128 /// Week number in the ISO week date (FW=PW=2).
129 IsoWeek,
130 /// Day of the week, where Sunday = 0 and Saturday = 6 (FW=PW=1).
131 NumDaysFromSun,
132 /// Day of the week, where Monday = 1 and Sunday = 7 (FW=PW=1).
133 WeekdayFromMon,
134 /// Day of the year (FW=PW=3).
135 Ordinal,
136 /// Hour number in the 24-hour clocks (FW=PW=2).
137 Hour,
138 /// Hour number in the 12-hour clocks (FW=PW=2).
139 Hour12,
140 /// The number of minutes since the last whole hour (FW=PW=2).
141 Minute,
142 /// The number of seconds since the last whole minute (FW=PW=2).
143 Second,
144 /// The number of nanoseconds since the last whole second (FW=PW=9).
145 /// Note that this is *not* left-aligned;
146 /// see also [`Fixed::Nanosecond`](./enum.Fixed.html#variant.Nanosecond).
147 Nanosecond,
148 /// The number of non-leap seconds since the midnight UTC on January 1, 1970 (FW=1, PW=∞).
149 /// For formatting, it assumes UTC upon the absence of time zone offset.
150 Timestamp,
151
152 /// Internal uses only.
153 ///
154 /// This item exists so that one can add additional internal-only formatting
155 /// without breaking major compatibility (as enum variants cannot be selectively private).
156 Internal(InternalNumeric),
157}
158
159/// An opaque type representing numeric item types for internal uses only.
160#[derive(Clone, Eq, Hash, PartialEq)]
161pub struct InternalNumeric {
162 _dummy: Void,
163}
164
165impl fmt::Debug for InternalNumeric {
166 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
167 write!(f, "<InternalNumeric>")
168 }
169}
170
171/// Fixed-format item types.
172///
173/// They have their own rules of formatting and parsing.
174/// Otherwise noted, they print in the specified cases but parse case-insensitively.
175#[non_exhaustive]
176#[derive(Clone, PartialEq, Eq, Debug, Hash)]
177pub enum Fixed {
178 /// Abbreviated month names.
179 ///
180 /// Prints a three-letter-long name in the title case, reads the same name in any case.
181 ShortMonthName,
182 /// Full month names.
183 ///
184 /// Prints a full name in the title case, reads either a short or full name in any case.
185 LongMonthName,
186 /// Abbreviated day of the week names.
187 ///
188 /// Prints a three-letter-long name in the title case, reads the same name in any case.
189 ShortWeekdayName,
190 /// Full day of the week names.
191 ///
192 /// Prints a full name in the title case, reads either a short or full name in any case.
193 LongWeekdayName,
194 /// AM/PM.
195 ///
196 /// Prints in lower case, reads in any case.
197 LowerAmPm,
198 /// AM/PM.
199 ///
200 /// Prints in upper case, reads in any case.
201 UpperAmPm,
202 /// An optional dot plus one or more digits for left-aligned nanoseconds.
203 /// May print nothing, 3, 6 or 9 digits according to the available accuracy.
204 /// See also [`Numeric::Nanosecond`](./enum.Numeric.html#variant.Nanosecond).
205 Nanosecond,
206 /// Same as [`Nanosecond`](#variant.Nanosecond) but the accuracy is fixed to 3.
207 Nanosecond3,
208 /// Same as [`Nanosecond`](#variant.Nanosecond) but the accuracy is fixed to 6.
209 Nanosecond6,
210 /// Same as [`Nanosecond`](#variant.Nanosecond) but the accuracy is fixed to 9.
211 Nanosecond9,
212 /// Timezone name.
213 ///
214 /// It does not support parsing, its use in the parser is an immediate failure.
215 TimezoneName,
216 /// Offset from the local time to UTC (`+09:00` or `-04:00` or `+00:00`).
217 ///
218 /// In the parser, the colon can be omitted and/or surrounded with any amount of whitespace.
219 /// The offset is limited from `-24:00` to `+24:00`,
220 /// which is the same as [`FixedOffset`](../offset/struct.FixedOffset.html)'s range.
221 TimezoneOffsetColon,
222 /// Offset from the local time to UTC with seconds (`+09:00:00` or `-04:00:00` or `+00:00:00`).
223 ///
224 /// In the parser, the colon can be omitted and/or surrounded with any amount of whitespace.
225 /// The offset is limited from `-24:00:00` to `+24:00:00`,
226 /// which is the same as [`FixedOffset`](../offset/struct.FixedOffset.html)'s range.
227 TimezoneOffsetDoubleColon,
228 /// Offset from the local time to UTC without minutes (`+09` or `-04` or `+00`).
229 ///
230 /// In the parser, the colon can be omitted and/or surrounded with any amount of whitespace.
231 /// The offset is limited from `-24` to `+24`,
232 /// which is the same as [`FixedOffset`](../offset/struct.FixedOffset.html)'s range.
233 TimezoneOffsetTripleColon,
234 /// Offset from the local time to UTC (`+09:00` or `-04:00` or `Z`).
235 ///
236 /// In the parser, the colon can be omitted and/or surrounded with any amount of whitespace,
237 /// and `Z` can be either in upper case or in lower case.
238 /// The offset is limited from `-24:00` to `+24:00`,
239 /// which is the same as [`FixedOffset`](../offset/struct.FixedOffset.html)'s range.
240 TimezoneOffsetColonZ,
241 /// Same as [`TimezoneOffsetColon`](#variant.TimezoneOffsetColon) but prints no colon.
242 /// Parsing allows an optional colon.
243 TimezoneOffset,
244 /// Same as [`TimezoneOffsetColonZ`](#variant.TimezoneOffsetColonZ) but prints no colon.
245 /// Parsing allows an optional colon.
246 TimezoneOffsetZ,
247 /// RFC 2822 date and time syntax. Commonly used for email and MIME date and time.
248 RFC2822,
249 /// RFC 3339 & ISO 8601 date and time syntax.
250 RFC3339,
251
252 /// Internal uses only.
253 ///
254 /// This item exists so that one can add additional internal-only formatting
255 /// without breaking major compatibility (as enum variants cannot be selectively private).
256 Internal(InternalFixed),
257}
258
259/// An opaque type representing fixed-format item types for internal uses only.
260#[derive(Debug, Clone, PartialEq, Eq, Hash)]
261pub struct InternalFixed {
262 val: InternalInternal,
263}
264
265#[derive(Debug, Clone, PartialEq, Eq, Hash)]
266enum InternalInternal {
267 /// Same as [`TimezoneOffsetColonZ`](#variant.TimezoneOffsetColonZ), but
268 /// allows missing minutes (per [ISO 8601][iso8601]).
269 ///
270 /// # Panics
271 ///
272 /// If you try to use this for printing.
273 ///
274 /// [iso8601]: https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC
275 TimezoneOffsetPermissive,
276 /// Same as [`Nanosecond`](#variant.Nanosecond) but the accuracy is fixed to 3 and there is no leading dot.
277 Nanosecond3NoDot,
278 /// Same as [`Nanosecond`](#variant.Nanosecond) but the accuracy is fixed to 6 and there is no leading dot.
279 Nanosecond6NoDot,
280 /// Same as [`Nanosecond`](#variant.Nanosecond) but the accuracy is fixed to 9 and there is no leading dot.
281 Nanosecond9NoDot,
282}
283
284/// Type for specifying the format of UTC offsets.
285#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
286pub struct OffsetFormat {
287 /// See `OffsetPrecision`.
288 pub precision: OffsetPrecision,
289 /// Separator between hours, minutes and seconds.
290 pub colons: Colons,
291 /// Represent `+00:00` as `Z`.
292 pub allow_zulu: bool,
293 /// Pad the hour value to two digits.
294 pub padding: Pad,
295}
296
297/// The precision of an offset from UTC formatting item.
298#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
299pub enum OffsetPrecision {
300 /// Format offset from UTC as only hours. Not recommended, it is not uncommon for timezones to
301 /// have an offset of 30 minutes, 15 minutes, etc.
302 /// Any minutes and seconds get truncated.
303 Hours,
304 /// Format offset from UTC as hours and minutes.
305 /// Any seconds will be rounded to the nearest minute.
306 Minutes,
307 /// Format offset from UTC as hours, minutes and seconds.
308 Seconds,
309 /// Format offset from UTC as hours, and optionally with minutes.
310 /// Any seconds will be rounded to the nearest minute.
311 OptionalMinutes,
312 /// Format offset from UTC as hours and minutes, and optionally seconds.
313 OptionalSeconds,
314 /// Format offset from UTC as hours and optionally minutes and seconds.
315 OptionalMinutesAndSeconds,
316}
317
318/// The separator between hours and minutes in an offset.
319#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
320pub enum Colons {
321 /// No separator
322 None,
323 /// Colon (`:`) as separator
324 Colon,
325 /// No separator when formatting, colon allowed when parsing.
326 Maybe,
327}
328
329/// A single formatting item. This is used for both formatting and parsing.
330#[derive(Clone, PartialEq, Eq, Debug, Hash)]
331pub enum Item<'a> {
332 /// A literally printed and parsed text.
333 Literal(&'a str),
334 /// Same as `Literal` but with the string owned by the item.
335 #[cfg(feature = "alloc")]
336 OwnedLiteral(Box<str>),
337 /// Whitespace. Prints literally but reads zero or more whitespace.
338 Space(&'a str),
339 /// Same as `Space` but with the string owned by the item.
340 #[cfg(feature = "alloc")]
341 OwnedSpace(Box<str>),
342 /// Numeric item. Can be optionally padded to the maximal length (if any) when formatting;
343 /// the parser simply ignores any padded whitespace and zeroes.
344 Numeric(Numeric, Pad),
345 /// Fixed-format item.
346 Fixed(Fixed),
347 /// Issues a formatting error. Used to signal an invalid format string.
348 Error,
349}
350
351const fn num(numeric: Numeric) -> Item<'static> {
352 Item::Numeric(numeric, Pad::None)
353}
354
355const fn num0(numeric: Numeric) -> Item<'static> {
356 Item::Numeric(numeric, Pad::Zero)
357}
358
359const fn nums(numeric: Numeric) -> Item<'static> {
360 Item::Numeric(numeric, Pad::Space)
361}
362
363const fn fixed(fixed: Fixed) -> Item<'static> {
364 Item::Fixed(fixed)
365}
366
367const fn internal_fixed(val: InternalInternal) -> Item<'static> {
368 Item::Fixed(Fixed::Internal(InternalFixed { val }))
369}
370
371impl Item<'_> {
372 /// Convert items that contain a reference to the format string into an owned variant.
373 #[cfg(any(feature = "alloc", feature = "std"))]
374 pub fn to_owned(self) -> Item<'static> {
375 match self {
376 Item::Literal(s: &str) => Item::OwnedLiteral(Box::from(s)),
377 Item::Space(s: &str) => Item::OwnedSpace(Box::from(s)),
378 Item::Numeric(n: Numeric, p: Pad) => Item::Numeric(n, p),
379 Item::Fixed(f: Fixed) => Item::Fixed(f),
380 Item::OwnedLiteral(l: Box) => Item::OwnedLiteral(l),
381 Item::OwnedSpace(s: Box) => Item::OwnedSpace(s),
382 Item::Error => Item::Error,
383 }
384 }
385}
386
387/// An error from the `parse` function.
388#[derive(Debug, Clone, PartialEq, Eq, Copy, Hash)]
389pub struct ParseError(ParseErrorKind);
390
391impl ParseError {
392 /// The category of parse error
393 pub const fn kind(&self) -> ParseErrorKind {
394 self.0
395 }
396}
397
398/// The category of parse error
399#[allow(clippy::manual_non_exhaustive)]
400#[derive(Debug, Clone, PartialEq, Eq, Copy, Hash)]
401pub enum ParseErrorKind {
402 /// Given field is out of permitted range.
403 OutOfRange,
404
405 /// There is no possible date and time value with given set of fields.
406 ///
407 /// This does not include the out-of-range conditions, which are trivially invalid.
408 /// It includes the case that there are one or more fields that are inconsistent to each other.
409 Impossible,
410
411 /// Given set of fields is not enough to make a requested date and time value.
412 ///
413 /// Note that there *may* be a case that given fields constrain the possible values so much
414 /// that there is a unique possible value. Chrono only tries to be correct for
415 /// most useful sets of fields however, as such constraint solving can be expensive.
416 NotEnough,
417
418 /// The input string has some invalid character sequence for given formatting items.
419 Invalid,
420
421 /// The input string has been prematurely ended.
422 TooShort,
423
424 /// All formatting items have been read but there is a remaining input.
425 TooLong,
426
427 /// There was an error on the formatting string, or there were non-supported formatting items.
428 BadFormat,
429
430 // TODO: Change this to `#[non_exhaustive]` (on the enum) with the next breaking release.
431 #[doc(hidden)]
432 __Nonexhaustive,
433}
434
435/// Same as `Result<T, ParseError>`.
436pub type ParseResult<T> = Result<T, ParseError>;
437
438impl fmt::Display for ParseError {
439 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
440 match self.0 {
441 ParseErrorKind::OutOfRange => write!(f, "input is out of range"),
442 ParseErrorKind::Impossible => write!(f, "no possible date and time matching input"),
443 ParseErrorKind::NotEnough => write!(f, "input is not enough for unique date and time"),
444 ParseErrorKind::Invalid => write!(f, "input contains invalid characters"),
445 ParseErrorKind::TooShort => write!(f, "premature end of input"),
446 ParseErrorKind::TooLong => write!(f, "trailing input"),
447 ParseErrorKind::BadFormat => write!(f, "bad or unsupported format string"),
448 _ => unreachable!(),
449 }
450 }
451}
452
453#[cfg(feature = "std")]
454impl Error for ParseError {
455 #[allow(deprecated)]
456 fn description(&self) -> &str {
457 "parser error, see to_string() for details"
458 }
459}
460
461// to be used in this module and submodules
462pub(crate) const OUT_OF_RANGE: ParseError = ParseError(ParseErrorKind::OutOfRange);
463const IMPOSSIBLE: ParseError = ParseError(ParseErrorKind::Impossible);
464const NOT_ENOUGH: ParseError = ParseError(ParseErrorKind::NotEnough);
465const INVALID: ParseError = ParseError(ParseErrorKind::Invalid);
466const TOO_SHORT: ParseError = ParseError(ParseErrorKind::TooShort);
467pub(crate) const TOO_LONG: ParseError = ParseError(ParseErrorKind::TooLong);
468const BAD_FORMAT: ParseError = ParseError(ParseErrorKind::BadFormat);
469
470// this implementation is here only because we need some private code from `scan`
471
472/// Parsing a `str` into a `Weekday` uses the format [`%A`](./format/strftime/index.html).
473///
474/// # Example
475///
476/// ```
477/// use chrono::Weekday;
478///
479/// assert_eq!("Sunday".parse::<Weekday>(), Ok(Weekday::Sun));
480/// assert!("any day".parse::<Weekday>().is_err());
481/// ```
482///
483/// The parsing is case-insensitive.
484///
485/// ```
486/// # use chrono::Weekday;
487/// assert_eq!("mON".parse::<Weekday>(), Ok(Weekday::Mon));
488/// ```
489///
490/// Only the shortest form (e.g. `sun`) and the longest form (e.g. `sunday`) is accepted.
491///
492/// ```
493/// # use chrono::Weekday;
494/// assert!("thurs".parse::<Weekday>().is_err());
495/// ```
496impl FromStr for Weekday {
497 type Err = ParseWeekdayError;
498
499 fn from_str(s: &str) -> Result<Self, Self::Err> {
500 if let Ok(("", w: Weekday)) = scan::short_or_long_weekday(s) {
501 Ok(w)
502 } else {
503 Err(ParseWeekdayError { _dummy: () })
504 }
505 }
506}
507
508/// Parsing a `str` into a `Month` uses the format [`%B`](./format/strftime/index.html).
509///
510/// # Example
511///
512/// ```
513/// use chrono::Month;
514///
515/// assert_eq!("January".parse::<Month>(), Ok(Month::January));
516/// assert!("any day".parse::<Month>().is_err());
517/// ```
518///
519/// The parsing is case-insensitive.
520///
521/// ```
522/// # use chrono::Month;
523/// assert_eq!("fEbruARy".parse::<Month>(), Ok(Month::February));
524/// ```
525///
526/// Only the shortest form (e.g. `jan`) and the longest form (e.g. `january`) is accepted.
527///
528/// ```
529/// # use chrono::Month;
530/// assert!("septem".parse::<Month>().is_err());
531/// assert!("Augustin".parse::<Month>().is_err());
532/// ```
533impl FromStr for Month {
534 type Err = ParseMonthError;
535
536 fn from_str(s: &str) -> Result<Self, Self::Err> {
537 if let Ok(("", w)) = scan::short_or_long_month0(s) {
538 match w {
539 0 => Ok(Month::January),
540 1 => Ok(Month::February),
541 2 => Ok(Month::March),
542 3 => Ok(Month::April),
543 4 => Ok(Month::May),
544 5 => Ok(Month::June),
545 6 => Ok(Month::July),
546 7 => Ok(Month::August),
547 8 => Ok(Month::September),
548 9 => Ok(Month::October),
549 10 => Ok(Month::November),
550 11 => Ok(Month::December),
551 _ => Err(ParseMonthError { _dummy: () }),
552 }
553 } else {
554 Err(ParseMonthError { _dummy: () })
555 }
556 }
557}
558