From cadf3394fea8ea22155cae08f8c0d19fe2550809 Mon Sep 17 00:00:00 2001 From: Paul Dicker Date: Tue, 6 Feb 2024 22:31:54 +0100 Subject: [PATCH] Improve documentation of `Parset::to_*` --- src/format/parsed.rs | 102 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 84 insertions(+), 18 deletions(-) diff --git a/src/format/parsed.rs b/src/format/parsed.rs index e6fef6d8c1..fac2cffe54 100644 --- a/src/format/parsed.rs +++ b/src/format/parsed.rs @@ -570,6 +570,18 @@ impl Parsed { /// /// Gregorian year and ISO week date year can have their century number (`*_div_100`) omitted, /// the two-digit year is used to guess the century number then. + /// + /// It checks all given date fields are consistent with each other. + /// + /// # Errors + /// + /// This method returns: + /// - `IMPOSSIBLE` if any of the date fields conflict. + /// - `NOT_ENOUGH` if there are not enough fields set in `Parsed` for a complete date. + /// - `OUT_OF_RANGE` + /// - if any of the date fields of `Parsed` are set to a value beyond their acceptable range. + /// - if the value would be outside the range of a [`NaiveDate`]. + /// - if the date does not exist. pub fn to_naive_date(&self) -> ParseResult { fn resolve_year( y: Option, @@ -776,6 +788,14 @@ impl Parsed { /// - Hour, minute, second, nanosecond. /// /// It is able to handle leap seconds when given second is 60. + /// + /// # Errors + /// + /// This method returns: + /// - `OUT_OF_RANGE` if any of the time fields of `Parsed` are set to a value beyond + /// their acceptable range. + /// - `NOT_ENOUGH` if an hour field is missing, if AM/PM is missing in a 12-hour clock, + /// if minutes are missing, or if seconds are missing while the nanosecond field is present. pub fn to_naive_time(&self) -> ParseResult { let hour_div_12 = match self.hour_div_12 { Some(v @ 0..=1) => v, @@ -811,13 +831,25 @@ impl Parsed { NaiveTime::from_hms_nano_opt(hour, minute, second, nano).ok_or(OUT_OF_RANGE) } - /// Returns a parsed naive date and time out of given fields, - /// except for the [`offset`](#structfield.offset) field (assumed to have a given value). - /// This is required for parsing a local time or other known-timezone inputs. + /// Returns a parsed naive date and time out of given fields, except for the offset field. + /// + /// The offset is assumed to have a given value. It is not compared against the offset field set + /// in the `Parsed` type, so it is allowed to be inconsistent. + /// + /// This method is able to determine the combined date and time from date and time fields or + /// from a single timestamp field. It checks all fields are consistent with each other. + /// + /// # Errors /// - /// This method is able to determine the combined date and time - /// from date and time fields or a single [`timestamp`](#structfield.timestamp) field. - /// Either way those fields have to be consistent to each other. + /// This method returns: + /// - `IMPOSSIBLE` if any of the date fields conflict, or if a timestamp conflicts with any of + /// the other fields. + /// - `NOT_ENOUGH` if there are not enough fields set in `Parsed` for a complete datetime. + /// - `OUT_OF_RANGE` + /// - if any of the date or time fields of `Parsed` are set to a value beyond their acceptable + /// range. + /// - if the value would be outside the range of a [`NaiveDateTime`]. + /// - if the date does not exist. pub fn to_naive_datetime_with_offset(&self, offset: i32) -> ParseResult { let date = self.to_naive_date(); let time = self.to_naive_time(); @@ -891,16 +923,34 @@ impl Parsed { } /// Returns a parsed fixed time zone offset out of given fields. + /// + /// # Errors + /// + /// This method returns: + /// - `OUT_OF_RANGE` if the offset is out of range for a `FixedOffset`. + /// - `NOT_ENOUGH` if the offset field is not set. pub fn to_fixed_offset(&self) -> ParseResult { FixedOffset::east_opt(self.offset.ok_or(NOT_ENOUGH)?).ok_or(OUT_OF_RANGE) } /// Returns a parsed timezone-aware date and time out of given fields. /// - /// This method is able to determine the combined date and time - /// from date and time fields or a single [`timestamp`](#structfield.timestamp) field, - /// plus a time zone offset. - /// Either way those fields have to be consistent to each other. + /// This method is able to determine the combined date and time from date, time and offset + /// fields, and/or from a single timestamp field. It checks all fields are consistent with each + /// other. + /// + /// # Errors + /// + /// This method returns: + /// - `IMPOSSIBLE` if any of the date fields conflict, or if a timestamp conflicts with any of + /// the other fields. + /// - `NOT_ENOUGH` if there are not enough fields set in `Parsed` for a complete datetime + /// including offset from UTC. + /// - `OUT_OF_RANGE` + /// - if any of the fields of `Parsed` are set to a value beyond their acceptable + /// range. + /// - if the value would be outside the range of a [`NaiveDateTime`] or [`FixedOffset`]. + /// - if the date does not exist. pub fn to_datetime(&self) -> ParseResult> { // If there is no explicit offset, consider a timestamp value as indication of a UTC value. let offset = match (self.offset, self.timestamp) { @@ -919,14 +969,30 @@ impl Parsed { } /// Returns a parsed timezone-aware date and time out of given fields, - /// with an additional `TimeZone` used to interpret and validate the local date. - /// - /// This method is able to determine the combined date and time - /// from date and time fields or a single [`timestamp`](#structfield.timestamp) field, - /// plus a time zone offset. - /// Either way those fields have to be consistent to each other. - /// If parsed fields include an UTC offset, it also has to be consistent to - /// [`offset`](#structfield.offset). + /// with an additional [`TimeZone`] used to interpret and validate the local date. + /// + /// This method is able to determine the combined date and time from date and time, and/or from + /// a single timestamp field. It checks all fields are consistent with each other. + /// + /// If the parsed fields include an UTC offset, it also has to be consistent with the offset in + /// the provided `tz` time zone for that datetime. + /// + /// # Errors + /// + /// This method returns: + /// - `IMPOSSIBLE` + /// - if any of the date fields conflict, if a timestamp conflicts with any of the other + /// fields, or if the offset field is set but differs from the offset at that time in the + /// `tz` time zone. + /// - if the local datetime does not exists in the provided time zone (because it falls in a + /// transition due to for example DST). + /// - `NOT_ENOUGH` if there are not enough fields set in `Parsed` for a complete datetime, or if + /// the local time in the provided time zone is ambiguous (because it falls in a transition + /// due to for example DST) while there is no offset field or timestamp field set. + /// - `OUT_OF_RANGE` + /// - if the value would be outside the range of a [`NaiveDateTime`] or [`FixedOffset`]. + /// - if any of the fields of `Parsed` are set to a value beyond their acceptable range. + /// - if the date does not exist. pub fn to_datetime_with_timezone(&self, tz: &Tz) -> ParseResult> { // if we have `timestamp` specified, guess an offset from that. let mut guessed_offset = 0;