Skip to content

Commit

Permalink
Add more documentation about the RFC 2822 obsolete date format
Browse files Browse the repository at this point in the history
  • Loading branch information
pitdicker committed Sep 8, 2023
1 parent 101ca7e commit 77d0bec
Showing 1 changed file with 17 additions and 5 deletions.
22 changes: 17 additions & 5 deletions src/datetime/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -666,10 +666,24 @@ impl DateTime<FixedOffset> {
/// and returns a new [`DateTime`] instance with the parsed timezone as the [`FixedOffset`].
///
/// RFC 2822 is the internet message standard that specifies the representation of times in HTTP
/// and email headers.
/// and email headers. It is the 2001 revision of RFC 822, and is itself revised as RFC 5322 in
/// 2008.
///
/// The RFC 2822 standard allows arbitrary intermixed whitespace.
/// See [RFC 2822 Appendix A.5]
/// # Support for the obsolete date format
///
/// - A 2-digit year is interpreted to be a year in 1950-2049.
/// - The standard allows comments and whitespace between many of the tokens. See [4.3] and
/// [Appendix A.5]
/// - Single letter 'military' time zone names are parsed as a `-0000` offset.
/// They were defined with the wrong sign in RFC 822 and corrected in RFC 2822. But because
/// the meaning is now ambiguous, the standard says they should be be considered as `-0000`
/// unless there is out-of-band information confirming their meaning.
/// The exception is `Z`, which remains identical to `+0000`.
///
/// [4.3]: https://www.rfc-editor.org/rfc/rfc2822#section-4.3
/// [Appendix A.5]: https://www.rfc-editor.org/rfc/rfc2822#appendix-A.5
///
/// # Example
///
/// ```
/// # use chrono::{DateTime, FixedOffset, TimeZone};
Expand All @@ -678,8 +692,6 @@ impl DateTime<FixedOffset> {
/// FixedOffset::east_opt(0).unwrap().with_ymd_and_hms(2015, 2, 18, 23, 16, 9).unwrap()
/// );
/// ```
///
/// [RFC 2822 Appendix A.5]: https://www.rfc-editor.org/rfc/rfc2822#appendix-A.5
pub fn parse_from_rfc2822(s: &str) -> ParseResult<DateTime<FixedOffset>> {
const ITEMS: &[Item<'static>] = &[Item::Fixed(Fixed::RFC2822)];
let mut parsed = Parsed::new();
Expand Down

0 comments on commit 77d0bec

Please sign in to comment.