Merge branch 'main' into TZ

Author: bezmuth

src/items/builder.rs

@@ -3,21 +3,21 @@
 
 use chrono::{DateTime, Datelike, FixedOffset, NaiveDate, TimeZone, Timelike};
 
-use super::{date, relative, time, weekday};
+use super::{date, relative, time, timezone, weekday, year};
 
 /// The builder is used to construct a DateTime object from various components.
 /// The parser creates a `DateTimeBuilder` object with the parsed components,
 /// but without the baseline date and time. So you normally need to set the base
 /// date and time using the `set_base()` method before calling `build()`, or
 /// leave it unset to use the current date and time as the base.
 #[derive(Debug, Default)]
-pub struct DateTimeBuilder {
+pub(crate) struct DateTimeBuilder {
     base: Option<DateTime<FixedOffset>>,
     timestamp: Option<f64>,
     date: Option<date::Date>,
     time: Option<time::Time>,
     weekday: Option<weekday::Weekday>,
-    timezone: Option<time::Offset>,
+    timezone: Option<timezone::Offset>,
     conversion_timezone: Option<FixedOffset>,
     relative: Vec<relative::Relative>,
 }
@@ -34,69 +34,70 @@ impl DateTimeBuilder {
         self
     }
 
-    /// Timestamp value is exclusive to other date/time components. Caller of
-    /// the builder must ensure that it is not combined with other items.
+    /// Sets a timestamp value. Timestamp values are exclusive to other date/time
+    /// items (date, time, weekday, timezone, relative adjustments).
     pub(super) fn set_timestamp(mut self, ts: f64) -> Result<Self, &'static str> {
+        if self.timestamp.is_some() {
+            return Err("timestamp cannot appear more than once");
+        } else if self.date.is_some()
+            || self.time.is_some()
+            || self.weekday.is_some()
+            || self.timezone.is_some()
+            || !self.relative.is_empty()
+        {
+            return Err("timestamp cannot be combined with other date/time items");
+        }
+
         self.timestamp = Some(ts);
         Ok(self)
     }
 
-    pub(super) fn set_year(mut self, year: u32) -> Result<Self, &'static str> {
-        if let Some(date) = self.date.as_mut() {
-            if date.year.is_some() {
-                Err("year cannot appear more than once")
-            } else {
-                date.year = Some(year);
-                Ok(self)
-            }
-        } else {
-            self.date = Some(date::Date {
-                day: 1,
-                month: 1,
-                year: Some(year),
-            });
-            Ok(self)
-        }
-    }
-
     pub(super) fn set_date(mut self, date: date::Date) -> Result<Self, &'static str> {
-        if self.date.is_some() || self.timestamp.is_some() {
-            Err("date cannot appear more than once")
-        } else {
-            self.date = Some(date);
-            Ok(self)
+        if self.timestamp.is_some() {
+            return Err("timestamp cannot be combined with other date/time items");
+        } else if self.date.is_some() {
+            return Err("date cannot appear more than once");
         }
+
+        self.date = Some(date);
+        Ok(self)
     }
 
     pub(super) fn set_time(mut self, time: time::Time) -> Result<Self, &'static str> {
-        if self.time.is_some() || self.timestamp.is_some() {
-            Err("time cannot appear more than once")
+        if self.timestamp.is_some() {
+            return Err("timestamp cannot be combined with other date/time items");
+        } else if self.time.is_some() {
+            return Err("time cannot appear more than once");
         } else if self.timezone.is_some() && time.offset.is_some() {
-            Err("time offset and timezone are mutually exclusive")
-        } else {
-            self.time = Some(time);
-            Ok(self)
+            return Err("time offset and timezone are mutually exclusive");
         }
+
+        self.time = Some(time);
+        Ok(self)
     }
 
     pub(super) fn set_weekday(mut self, weekday: weekday::Weekday) -> Result<Self, &'static str> {
-        if self.weekday.is_some() {
-            Err("weekday cannot appear more than once")
-        } else {
-            self.weekday = Some(weekday);
-            Ok(self)
+        if self.timestamp.is_some() {
+            return Err("timestamp cannot be combined with other date/time items");
+        } else if self.weekday.is_some() {
+            return Err("weekday cannot appear more than once");
         }
+
+        self.weekday = Some(weekday);
+        Ok(self)
     }
 
-    pub(super) fn set_timezone(mut self, timezone: time::Offset) -> Result<Self, &'static str> {
-        if self.timezone.is_some() {
-            Err("timezone cannot appear more than once")
+    pub(super) fn set_timezone(mut self, timezone: timezone::Offset) -> Result<Self, &'static str> {
+        if self.timestamp.is_some() {
+            return Err("timestamp cannot be combined with other date/time items");
+        } else if self.timezone.is_some() {
+            return Err("timezone cannot appear more than once");
         } else if self.time.as_ref().and_then(|t| t.offset.as_ref()).is_some() {
-            Err("time offset and timezone are mutually exclusive")
-        } else {
-            self.timezone = Some(timezone);
-            Ok(self)
+            return Err("time offset and timezone are mutually exclusive");
         }
+
+        self.timezone = Some(timezone);
+        Ok(self)
     }
 
     pub(super) fn set_conversion_timezone(
@@ -111,14 +112,77 @@ impl DateTimeBuilder {
         }
     }
 
-    pub(super) fn push_relative(mut self, relative: relative::Relative) -> Self {
+    pub(super) fn push_relative(
+        mut self,
+        relative: relative::Relative,
+    ) -> Result<Self, &'static str> {
+        if self.timestamp.is_some() {
+            return Err("timestamp cannot be combined with other date/time items");
+        }
         self.relative.push(relative);
-        self
+        Ok(self)
+    }
+
+    /// Sets a pure number that can be interpreted as either a year or time
+    /// depending on the current state of the builder.
+    ///
+    /// If a date is already set but lacks a year, the number is interpreted as
+    /// a year. Otherwise, it's interpreted as a time in HHMM, HMM, HH, or H
+    /// format.
+    pub(super) fn set_pure(mut self, pure: String) -> Result<Self, &'static str> {
+        if self.timestamp.is_some() {
+            return Err("timestamp cannot be combined with other date/time items");
+        }
+
+        if let Some(date) = self.date.as_mut() {
+            if date.year.is_none() {
+                date.year = Some(year::year_from_str(&pure)?);
+                return Ok(self);
+            }
+        }
+
+        let (mut hour_str, mut minute_str) = match pure.len() {
+            1..=2 => (pure.as_str(), "0"),
+            3..=4 => pure.split_at(pure.len() - 2),
+            _ => {
+                return Err("pure number must be 1-4 digits when interpreted as time");
+            }
+        };
+
+        let hour = time::hour24(&mut hour_str).map_err(|_| "invalid hour in pure number")?;
+        let minute = time::minute(&mut minute_str).map_err(|_| "invalid minute in pure number")?;
+
+        let time = time::Time {
+            hour,
+            minute,
+            ..Default::default()
+        };
+        self.set_time(time)
+    }
+
+    fn build_from_timestamp(ts: f64, tz: &FixedOffset) -> Option<DateTime<FixedOffset>> {
+        // TODO: How to make the fract -> nanosecond conversion more precise?
+        // Maybe considering using the
+        // [rust_decimal](https://crates.io/crates/rust_decimal) crate?
+        match chrono::Utc.timestamp_opt(ts as i64, (ts.fract() * 10f64.powi(9)).round() as u32) {
+            chrono::MappedLocalTime::Single(t) => Some(t.with_timezone(tz)),
+            chrono::MappedLocalTime::Ambiguous(earliest, _latest) => {
+                // TODO: When there is a fold in the local time, which value
+                // do we choose? For now, we use the earliest one.
+                Some(earliest.with_timezone(tz))
+            }
+            chrono::MappedLocalTime::None => None, // Invalid timestamp
+        }
     }
 
     pub(super) fn build(self) -> Option<DateTime<FixedOffset>> {
         let base = self.base.unwrap_or_else(|| chrono::Local::now().into());
 
+        // If a timestamp is set, we use it to build the DateTime object.
+        if let Some(ts) = self.timestamp {
+            return Self::build_from_timestamp(ts, base.offset());
+        }
+
         // If any of the following items are set, we truncate the time portion
         // of the base date to zero; otherwise, we use the base date as is.
         let mut dt = if self.timestamp.is_none()
@@ -141,27 +205,6 @@ impl DateTimeBuilder {
             )?
         };
 
-        if let Some(ts) = self.timestamp {
-            // TODO: How to make the fract -> nanosecond conversion more precise?
-            // Maybe considering using the
-            // [rust_decimal](https://crates.io/crates/rust_decimal) crate?
-            match chrono::Utc.timestamp_opt(ts as i64, (ts.fract() * 10f64.powi(9)).round() as u32)
-            {
-                chrono::MappedLocalTime::Single(t) => {
-                    // If the timestamp is valid, we can use it directly.
-                    dt = t.with_timezone(&dt.timezone());
-                }
-                chrono::MappedLocalTime::Ambiguous(earliest, _latest) => {
-                    // TODO: When there is a fold in the local time, which value
-                    // do we choose? For now, we use the earliest one.
-                    dt = earliest.with_timezone(&dt.timezone());
-                }
-                chrono::MappedLocalTime::None => {
-                    return None; // Invalid timestamp
-                }
-            }
-        }
-
         if let Some(date::Date { year, month, day }) = self.date {
             dt = new_date(
                 year.map(|x| x as i32).unwrap_or(dt.year()),
@@ -292,7 +335,7 @@ impl DateTimeBuilder {
     }
 }
 
-#[allow(clippy::too_many_arguments)]
+#[allow(clippy::too_many_arguments, deprecated)]
 fn new_date(
     year: i32,
     month: u32,

src/items/combined.rs

@@ -21,16 +21,12 @@ use winnow::{
 
 use crate::items::space;
 
-use super::{
-    date::{self, Date},
-    primitive::s,
-    time::{self, Time},
-};
+use super::{date, primitive::s, time};
 
 #[derive(PartialEq, Debug, Clone, Default)]
 pub(crate) struct DateTime {
-    pub(crate) date: Date,
-    pub(crate) time: Time,
+    pub(crate) date: date::Date,
+    pub(crate) time: time::Time,
 }
 
 pub(crate) fn parse(input: &mut &str) -> ModalResult<DateTime> {

src/items/epoch.rs

@@ -1,6 +1,20 @@
 // For the full copyright and license information, please view the LICENSE
 // file that was distributed with this source code.
 
+//! From the GNU docs:
+//!
+//! > If you precede a number with ‘@’, it represents an internal timestamp as
+//! > a count of seconds.  The number can contain an internal decimal point
+//! > (either ‘.’ or ‘,’); any excess precision not supported by the internal
+//! > representation is truncated toward minus infinity.  Such a number cannot
+//! > be combined with any other date item, as it specifies a complete
+//! > timestamp.
+//! >
+//! >    On most hosts, these counts ignore the presence of leap seconds.  For
+//! > example, on most hosts ‘@1483228799’ represents 2016-12-31 23:59:59 UTC,
+//! > ‘@1483228800’ represents 2017-01-01 00:00:00 UTC, and there is no way to
+//! > represent the intervening leap second 2016-12-31 23:59:60 UTC.
+
 use winnow::{combinator::preceded, ModalResult, Parser};
 
 use super::primitive::{float, s};