Skip to content

Commit

Permalink
Improve documentation of Parset::to_*
Browse files Browse the repository at this point in the history
  • Loading branch information
pitdicker committed Feb 16, 2024
1 parent 73f2dc9 commit 8b66a78
Showing 1 changed file with 81 additions and 18 deletions.
99 changes: 81 additions & 18 deletions src/format/parsed.rs
Original file line number Diff line number Diff line change
Expand Up @@ -571,6 +571,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.
/// - `OUT_OF_RANGE` if any of the date fields of `Parsed` are set to a value beyond
/// their acceptable range.
/// - `OUT_OF_RANGE` if the value would be outside the range of a `NaiveDate`.
/// - `NOT_ENOUGH` if there are not enough fields set in `Parsed` for a complete date.
/// - `OUT_OF_RANGE` if the date does not exist.
pub fn to_naive_date(&self) -> ParseResult<NaiveDate> {
fn resolve_year(
y: Option<i32>,
Expand Down Expand Up @@ -777,6 +789,14 @@ impl Parsed {
/// - Hour, minute, second, nanosecond.
///
/// It is able to handle leap seconds when given second is 60.
///
/// # Errors
///
/// This method returns:
/// - Returns `OUT_OF_RANGE` if any of the time fields of `Parsed` are set to a value beyond
/// their acceptable range.
/// - Returns `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<NaiveTime> {
let hour_div_12 = match self.hour_div_12 {
Some(v @ 0..=1) => v,
Expand Down Expand Up @@ -812,13 +832,24 @@ 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.
/// - `OUT_OF_RANGE` if any of the date or time fields of `Parsed` are set to a value beyond
/// their acceptable range.
/// - `OUT_OF_RANGE` if the value would be outside the range of a `NaiveDate`.
/// - `NOT_ENOUGH` if there are not enough fields set in `Parsed` for a complete datetime.
/// - `OUT_OF_RANGE` if the date does not exist.
pub fn to_naive_datetime_with_offset(&self, offset: i32) -> ParseResult<NaiveDateTime> {
let date = self.to_naive_date();
let time = self.to_naive_time();
Expand Down Expand Up @@ -892,16 +923,32 @@ impl Parsed {
}

/// Returns a parsed fixed time zone offset out of given fields.
///
/// # Errors
///
/// Returns `OUT_OF_RANGE` if the offset is out of range for a `FixedOffset`.
pub fn to_fixed_offset(&self) -> ParseResult<FixedOffset> {
self.offset.and_then(FixedOffset::east_opt).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.
/// - `OUT_OF_RANGE` if any of the fields of `Parsed` are set to a value beyond their acceptable
/// range.
/// - `OUT_OF_RANGE` if the value would be outside the range of a [`NaiveDateTime`] or
/// [`FixedOffset`].
/// - `NOT_ENOUGH` if there are not enough fields set in `Parsed` for a complete datetime
/// including offset from UTC.
/// - `OUT_OF_RANGE` if the date does not exist.
pub fn to_datetime(&self) -> ParseResult<DateTime<FixedOffset>> {
// If there is no explicit offset, consider a timestamp value as indication of a UTC value.
let offset = match (self.offset, self.timestamp) {
Expand All @@ -920,14 +967,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.
/// - `OUT_OF_RANGE` if the value would be outside the range of a [`NaiveDateTime`] or
/// [`FixedOffset`].
/// - `OUT_OF_RANGE` if any of the fields of `Parsed` are set to a value beyond their acceptable
/// range.
/// - `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 date does not exist, or `IMPOSSIBLE` if the local datetime does not
/// exists in the provided time zone (because it falls in a transition due to for example
/// DST).
pub fn to_datetime_with_timezone<Tz: TimeZone>(&self, tz: &Tz) -> ParseResult<DateTime<Tz>> {
// if we have `timestamp` specified, guess an offset from that.
let mut guessed_offset = 0;
Expand Down

0 comments on commit 8b66a78

Please sign in to comment.