diff --git a/src/format/parsed.rs b/src/format/parsed.rs index 654aece375..cdd328a995 100644 --- a/src/format/parsed.rs +++ b/src/format/parsed.rs @@ -11,7 +11,7 @@ use crate::{DateTime, Datelike, TimeDelta, Timelike, Weekday}; /// A type to hold parsed fields of date and time that can check all fields are consistent. /// -/// There are two classes of methods: +/// There are three classes of methods: /// /// - `set_*` methods to set fields you have available. They do a basic range check, and if the /// same field is set more than once it is checked for consistency. @@ -19,6 +19,8 @@ use crate::{DateTime, Datelike, TimeDelta, Timelike, Weekday}; /// - `to_*` methods try to make a concrete date and time value out of set fields. /// They fully check that all fields are consistent and whether the date/datetime exists. /// +/// - Methods to inspect the parsed fields. +/// /// `Parsed` is used internally by all parsing functions in chrono. It is a public type so that it /// can be used to write custom parsers that reuse the resolving algorithm, or to inspect the /// results of a string parsed with chrono without converting it to concrete types. @@ -116,7 +118,7 @@ use crate::{DateTime, Datelike, TimeDelta, Timelike, Weekday}; /// assert!(result.is_err()); /// if result.is_err() { /// // What is the weekday? -/// assert_eq!(parsed.weekday, Some(Weekday::Thu)); +/// assert_eq!(parsed.weekday(), Some(Weekday::Thu)); /// } /// # Ok::<(), chrono::ParseError>(()) /// ``` @@ -232,9 +234,10 @@ impl Parsed { Parsed::default() } - /// Set the 'year' field to the given value. + /// Set the [`year`](Parsed::year) field to the given value. /// - /// The value can be negative, unlike the 'year divided by 100' and 'year modulo 100' fields. + /// The value can be negative, unlike the [`year_div_100`](Parsed::year_div_100) and + /// [`year_mod_100`](Parsed::year_mod_100) fields. /// /// # Errors /// @@ -246,7 +249,7 @@ impl Parsed { set_if_consistent(&mut self.year, i32::try_from(value).map_err(|_| OUT_OF_RANGE)?) } - /// Set the 'year divided by 100' field to the given value. + /// Set the [`year_div_100`](Parsed::year_div_100) field to the given value. /// /// # Errors /// @@ -261,12 +264,13 @@ impl Parsed { set_if_consistent(&mut self.year_div_100, value as i32) } - /// Set the 'year modulo 100' field to the given value. + /// Set the [`year_mod_100`](Parsed::year_mod_100) field to the given value. /// /// When set it implies that the year is not negative. /// - /// If this field is set while the 'year divided by 100' field is missing (and the full 'year' - /// field is also not set), it assumes a default value for the 'year divided by 100' field. + /// If this field is set while the [`year_div_100`](Parsed::year_div_100) field is missing (and + /// the full [`year`](Parsed::year) field is also not set), it assumes a default value for the + /// [`year_div_100`](Parsed::year_div_100) field. /// The default is 19 when `year_mod_100 >= 70` and 20 otherwise. /// /// # Errors @@ -282,9 +286,11 @@ impl Parsed { set_if_consistent(&mut self.year_mod_100, value as i32) } - /// Set the 'year' field that is part of an [ISO 8601 week date] to the given value. + /// Set the [`isoyear`](Parsed::isoyear) field, that is part of an [ISO 8601 week date], to the + /// given value. /// - /// The value can be negative, unlike the 'year divided by 100' and 'year modulo 100' fields. + /// The value can be negative, unlike the [`isoyear_div_100`](Parsed::isoyear_div_100) and + /// [`isoyear_mod_100`](Parsed::isoyear_mod_100) fields. /// /// [ISO 8601 week date]: crate::NaiveDate#week-date /// @@ -298,8 +304,8 @@ impl Parsed { set_if_consistent(&mut self.isoyear, i32::try_from(value).map_err(|_| OUT_OF_RANGE)?) } - /// Set the 'year divided by 100' field that is part of an [ISO 8601 week date] to the given - /// value. + /// Set the [`isoyear_div_100`](Parsed::isoyear_div_100) field, that is part of an + /// [ISO 8601 week date], to the given value. /// /// [ISO 8601 week date]: crate::NaiveDate#week-date /// @@ -316,12 +322,14 @@ impl Parsed { set_if_consistent(&mut self.isoyear_div_100, value as i32) } - /// Set the 'year modulo 100' that is part of an [ISO 8601 week date] field to the given value. + /// Set the [`isoyear_mod_100`](Parsed::isoyear_mod_100) field, that is part of an + /// [ISO 8601 week date], to the given value. /// /// When set it implies that the year is not negative. /// - /// If this field is set while the 'year divided by 100' field is missing (and the full `year` - /// field is also not set), it assumes a default value for the 'year divided by 100' field. + /// If this field is set while the [`isoyear_div_100`](Parsed::isoyear_div_100) field is missing + /// (and the full [`isoyear`](Parsed::isoyear) field is also not set), it assumes a default + /// value for the [`isoyear_div_100`](Parsed::isoyear_div_100) field. /// The default is 19 when `year_mod_100 >= 70` and 20 otherwise. /// /// [ISO 8601 week date]: crate::NaiveDate#week-date @@ -339,7 +347,7 @@ impl Parsed { set_if_consistent(&mut self.isoyear_mod_100, value as i32) } - /// Set the 'month' field to the given value. + /// Set the [`month`](Parsed::month) field to the given value. /// /// # Errors /// @@ -354,7 +362,7 @@ impl Parsed { set_if_consistent(&mut self.month, value as u32) } - /// Set the 'week number starting with Sunday' field to the given value. + /// Set the [`week_from_sun`](Parsed::week_from_sun) week number field to the given value. /// /// Week 1 starts at the first Sunday of January. /// @@ -371,6 +379,7 @@ impl Parsed { set_if_consistent(&mut self.week_from_sun, value as u32) } + /// Set the [`week_from_mon`](Parsed::week_from_mon) week number field to the given value. /// Set the 'week number starting with Monday' field to the given value. /// /// Week 1 starts at the first Monday of January. @@ -388,9 +397,9 @@ impl Parsed { set_if_consistent(&mut self.week_from_mon, value as u32) } - /// Set the '[ISO 8601 week number]' field to the given value. + /// Set the [`isoweek`](Parsed::isoweek) field for an [ISO 8601 week date] to the given value. /// - /// [ISO 8601 week number]: crate::NaiveDate#week-date + /// [ISO 8601 week date]: crate::NaiveDate#week-date /// /// # Errors /// @@ -405,7 +414,7 @@ impl Parsed { set_if_consistent(&mut self.isoweek, value as u32) } - /// Set the 'day of the week' field to the given value. + /// Set the [`weekday`](Parsed::weekday) field to the given value. /// /// # Errors /// @@ -415,7 +424,7 @@ impl Parsed { set_if_consistent(&mut self.weekday, value) } - /// Set the 'ordinal' (day of the year) field to the given value. + /// Set the [`ordinal`](Parsed::ordinal) (day of the year) field to the given value. /// /// # Errors /// @@ -430,7 +439,7 @@ impl Parsed { set_if_consistent(&mut self.ordinal, value as u32) } - /// Set the 'day of the month' field to the given value. + /// Set the [`day`](Parsed::day) of the month field to the given value. /// /// # Errors /// @@ -445,7 +454,7 @@ impl Parsed { set_if_consistent(&mut self.day, value as u32) } - /// Set the 'am/pm' field to the given value. + /// Set the [`hour_div_12`](Parsed::hour_div_12) am/pm field to the given value. /// /// `false` indicates AM and `true` indicates PM. /// @@ -457,7 +466,8 @@ impl Parsed { set_if_consistent(&mut self.hour_div_12, value as u32) } - /// Set the 'hour number in 12-hour clocks' field to the given value. + /// Set the [`hour_mod_12`](Parsed::hour_mod_12) field, for the hour number in 12-hour clocks, + /// to the given value. /// /// Value must be in the canonical range of 1-12. /// It will internally be stored as 0-11 (`value % 12`). @@ -478,9 +488,8 @@ impl Parsed { set_if_consistent(&mut self.hour_mod_12, value as u32) } - /// Set the 'hour' field to the given value. - /// - /// Internally this sets the 'hour modulo 12' and 'am/pm' fields. + /// Set the [`hour_div_12`](Parsed::hour_div_12) and [`hour_mod_12`](Parsed::hour_mod_12) + /// fields to the given value for a 24-hour clock. /// /// # Errors /// @@ -499,7 +508,7 @@ impl Parsed { set_if_consistent(&mut self.hour_mod_12, hour_mod_12) } - /// Set the 'minute' field to the given value. + /// Set the [`minute`](Parsed::minute) field to the given value. /// /// # Errors /// @@ -514,7 +523,7 @@ impl Parsed { set_if_consistent(&mut self.minute, value as u32) } - /// Set the 'second' field to the given value. + /// Set the [`second`](Parsed::second) field to the given value. /// /// The value can be 60 in the case of a leap second. /// @@ -531,7 +540,7 @@ impl Parsed { set_if_consistent(&mut self.second, value as u32) } - /// Set the 'nanosecond' field to the given value. + /// Set the [`nanosecond`](Parsed::nanosecond) field to the given value. /// /// This is the number of nanoseconds since the whole second. /// @@ -548,7 +557,7 @@ impl Parsed { set_if_consistent(&mut self.nanosecond, value as u32) } - /// Set the 'timestamp' field to the given value. + /// Set the [`timestamp`](Parsed::timestamp) field to the given value. /// /// A Unix timestamp is defined as the number of non-leap seconds since midnight UTC on /// January 1, 1970. @@ -561,9 +570,9 @@ impl Parsed { set_if_consistent(&mut self.timestamp, value) } - /// Set the 'offset from local time to UTC' field to the given value. + /// Set the [`offset`](Parsed::offset) field to the given value. /// - /// The offset is in seconds. + /// The offset is in seconds from local time to UTC. /// /// # Errors /// @@ -1053,6 +1062,175 @@ impl Parsed { } } } + + /// Get the `year` field if set. + /// + /// See also [`set_year()`](Parsed::set_year). + #[inline] + pub fn year(&self) -> Option { + self.year + } + + /// Get the `year_div_100` field if set. + /// + /// See also [`set_year_div_100()`](Parsed::set_year_div_100). + #[inline] + pub fn year_div_100(&self) -> Option { + self.year_div_100 + } + + /// Get the `year_mod_100` field if set. + /// + /// See also [`set_year_mod_100()`](Parsed::set_year_mod_100). + #[inline] + pub fn year_mod_100(&self) -> Option { + self.year_mod_100 + } + + /// Get the `isoyear` field that is part of an [ISO 8601 week date] if set. + /// + /// See also [`set_isoyear()`](Parsed::set_isoyear). + /// + /// [ISO 8601 week date]: crate::NaiveDate#week-date + #[inline] + pub fn isoyear(&self) -> Option { + self.isoyear + } + + /// Get the `isoyear_div_100` field that is part of an [ISO 8601 week date] if set. + /// + /// See also [`set_isoyear_div_100()`](Parsed::set_isoyear_div_100). + /// + /// [ISO 8601 week date]: crate::NaiveDate#week-date + #[inline] + pub fn isoyear_div_100(&self) -> Option { + self.isoyear_div_100 + } + + /// Get the `isoyear_mod_100` field that is part of an [ISO 8601 week date] if set. + /// + /// See also [`set_isoyear_mod_100()`](Parsed::set_isoyear_mod_100). + /// + /// [ISO 8601 week date]: crate::NaiveDate#week-date + #[inline] + pub fn isoyear_mod_100(&self) -> Option { + self.isoyear_mod_100 + } + + /// Get the `month` field if set. + /// + /// See also [`set_month()`](Parsed::set_month). + #[inline] + pub fn month(&self) -> Option { + self.month + } + + /// Get the `week_from_sun` field if set. + /// + /// See also [`set_week_from_sun()`](Parsed::set_week_from_sun). + #[inline] + pub fn week_from_sun(&self) -> Option { + self.week_from_sun + } + + /// Get the `week_from_mon` field if set. + /// + /// See also [`set_week_from_mon()`](Parsed::set_week_from_mon). + #[inline] + pub fn week_from_mon(&self) -> Option { + self.week_from_mon + } + + /// Get the `isoweek` field that is part of an [ISO 8601 week date] if set. + /// + /// See also [`set_isoweek()`](Parsed::set_isoweek). + /// + /// [ISO 8601 week date]: crate::NaiveDate#week-date + #[inline] + pub fn isoweek(&self) -> Option { + self.isoweek + } + + /// Get the `weekday` field if set. + /// + /// See also [`set_weekday()`](Parsed::set_weekday). + #[inline] + pub fn weekday(&self) -> Option { + self.weekday + } + + /// Get the `ordinal` (day of the year) field if set. + /// + /// See also [`set_ordinal()`](Parsed::set_ordinal). + #[inline] + pub fn ordinal(&self) -> Option { + self.ordinal + } + + /// Get the `day` of the month field if set. + /// + /// See also [`set_day()`](Parsed::set_day). + #[inline] + pub fn day(&self) -> Option { + self.day + } + + /// Get the `hour_div_12` field (am/pm) if set. + /// + /// 0 indicates AM and 1 indicates PM. + /// + /// See also [`set_ampm()`](Parsed::set_ampm) and [`set_hour()`](Parsed::set_hour). + #[inline] + pub fn hour_div_12(&self) -> Option { + self.hour_div_12 + } + + /// Get the `hour_mod_12` field if set. + /// + /// See also [`set_hour12()`](Parsed::set_hour12) and [`set_hour()`](Parsed::set_hour). + pub fn hour_mod_12(&self) -> Option { + self.hour_mod_12 + } + + /// Get the `minute` field if set. + /// + /// See also [`set_minute()`](Parsed::set_minute). + #[inline] + pub fn minute(&self) -> Option { + self.minute + } + + /// Get the `second` field if set. + /// + /// See also [`set_second()`](Parsed::set_second). + #[inline] + pub fn second(&self) -> Option { + self.second + } + + /// Get the `nanosecond` field if set. + /// + /// See also [`set_nanosecond()`](Parsed::set_nanosecond). + #[inline] + pub fn nanosecond(&self) -> Option { + self.nanosecond + } + + /// Get the `timestamp` field if set. + /// + /// See also [`set_timestamp()`](Parsed::set_timestamp). + #[inline] + pub fn timestamp(&self) -> Option { + self.timestamp + } + + /// Get the `offset` field if set. + /// + /// See also [`set_offset()`](Parsed::set_offset). + #[inline] + pub fn offset(&self) -> Option { + self.offset + } } #[cfg(test)]