fix!: turn SignatureRef::time field into &str.

We also add a `gix_date::Time::to_str()` method, along with related utilities,
to be able to turn a parsed time back into a raw buffer conveniently.

Further, remove `Time::to_bstring()` in favor of a `Display` implementation.

Author: Byron

Cargo.lock

@@ -6,8 +6,7 @@
     doc = ::document_features::document_features!()
 )]
 #![cfg_attr(all(doc, feature = "document-features"), feature(doc_cfg, doc_auto_cfg))]
-#![deny(missing_docs, rust_2018_idioms)]
-#![forbid(unsafe_code)]
+#![deny(missing_docs, rust_2018_idioms, unsafe_code)]
 
 /// The re-exported `bstr` crate.
 ///
@@ -85,6 +84,6 @@ pub struct SignatureRef<'a> {
     ///
     /// Use [SignatureRef::trim()] or trim manually to be able to clean it up.
     pub email: &'a BStr,
-    /// The time stamp at which the signature was performed.
-    pub time: &'a BStr,
+    /// The timestamp at which the signature was performed.
+    pub time: &'a str,
 }

gix-actor/src/lib.rs

@@ -23,9 +23,13 @@ pub(crate) mod function {
             ))
             .map(|maybe_bytes| {
                 if let Some((bytes,)) = maybe_bytes {
-                    bytes.into()
+                    // SAFETY: The parser validated that there are only ASCII characters.
+                    #[allow(unsafe_code)]
+                    unsafe {
+                        std::str::from_utf8_unchecked(bytes)
+                    }
                 } else {
-                    b"".into()
+                    ""
                 }
             }),
         )
@@ -82,7 +86,6 @@ pub use function::identity;
 mod tests {
     mod parse_signature {
         use crate::{signature, SignatureRef};
-        use bstr::ByteSlice;
         use gix_date::time::Sign;
         use gix_testtools::to_bstr_err;
         use winnow::prelude::*;
@@ -95,9 +98,9 @@ mod tests {
 
         fn signature(name: &'static str, email: &'static str, time: &'static str) -> SignatureRef<'static> {
             SignatureRef {
-                name: name.as_bytes().as_bstr(),
-                email: email.as_bytes().as_bstr(),
-                time: time.as_bytes().as_bstr(),
+                name: name.into(),
+                email: email.into(),
+                time,
             }
         }
 

gix-actor/src/signature/decode.rs

@@ -1,6 +1,5 @@
 mod _ref {
     use bstr::ByteSlice;
-    use gix_date::Time;
     use winnow::{error::StrContext, prelude::*};
 
     use crate::{signature::decode, IdentityRef, Signature, SignatureRef};
@@ -32,7 +31,7 @@ mod _ref {
             SignatureRef {
                 name: self.name.trim().as_bstr(),
                 email: self.email.trim().as_bstr(),
-                time: self.time.trim().as_bstr(),
+                time: self.time.trim(),
             }
         }
 
@@ -49,49 +48,52 @@ mod _ref {
         ///
         /// For a fallible and more complete, but slower version, use [`time()`](Self::time).
         pub fn seconds(&self) -> gix_date::SecondsSinceUnixEpoch {
-            use winnow::stream::AsChar;
             self.time
                 .trim()
-                .split(|b| b.is_space())
+                .split(' ')
                 .next()
-                .and_then(|i| i.to_str().ok()?.parse().ok())
+                .and_then(|i| i.parse().ok())
                 .unwrap_or_default()
         }
 
         /// Parse the `time` field for access to the passed time since unix epoch, and the time offset.
+        /// The format is expected to be [raw](gix_date::parse_header()).
         pub fn time(&self) -> Result<gix_date::Time, gix_date::parse::Error> {
-            Time::from_bytes(self.time)
+            self.time.parse()
         }
     }
 }
 
 mod convert {
     use crate::{Signature, SignatureRef};
+    use gix_date::parse::TimeBuf;
 
     impl Signature {
         /// Borrow this instance as immutable, serializing the `time` field into `buf`.
-        pub fn to_ref<'a>(&'a self, buf: &'a mut Vec<u8>) -> SignatureRef<'a> {
+        pub fn to_ref<'a>(&'a self, time_buf: &'a mut TimeBuf) -> SignatureRef<'a> {
             SignatureRef {
                 name: self.name.as_ref(),
                 email: self.email.as_ref(),
-                time: self.time.to_ref(buf),
+                time: self.time.to_str(time_buf),
             }
         }
     }
 
-    impl TryFrom<SignatureRef<'_>> for Signature {
-        type Error = gix_date::parse::Error;
-
-        fn try_from(other: SignatureRef<'_>) -> Result<Signature, Self::Error> {
-            other.to_owned()
+    impl From<SignatureRef<'_>> for Signature {
+        fn from(other: SignatureRef<'_>) -> Signature {
+            Signature {
+                name: other.name.to_owned(),
+                email: other.email.to_owned(),
+                time: other.time().unwrap_or_default(),
+            }
         }
     }
 }
 
 pub(crate) mod write {
-    use bstr::{BStr, ByteSlice};
-
     use crate::{Signature, SignatureRef};
+    use bstr::{BStr, ByteSlice};
+    use gix_date::parse::TimeBuf;
 
     /// The Error produced by [`Signature::write_to()`].
     #[derive(Debug, thiserror::Error)]
@@ -111,7 +113,7 @@ pub(crate) mod write {
     impl Signature {
         /// Serialize this instance to `out` in the git serialization format for actors.
         pub fn write_to(&self, out: &mut dyn std::io::Write) -> std::io::Result<()> {
-            let mut buf = Vec::<u8>::new();
+            let mut buf = TimeBuf::default();
             self.to_ref(&mut buf).write_to(out)
         }
         /// Computes the number of bytes necessary to serialize this signature
@@ -128,7 +130,7 @@ pub(crate) mod write {
             out.write_all(b"<")?;
             out.write_all(validated_token(self.email)?)?;
             out.write_all(b"> ")?;
-            out.write_all(validated_token(self.time)?)
+            out.write_all(validated_token(self.time.into())?)
         }
         /// Computes the number of bytes necessary to serialize this signature
         pub fn size(&self) -> usize {

gix-actor/src/signature/mod.rs

@@ -24,6 +24,9 @@ serde = { version = "1.0.114", optional = true, default-features = false, featur
 itoa = "1.0.1"
 jiff = "0.2.6"
 thiserror = "2.0.0"
+# TODO: used for quick and easy `TimeBacking: std::io::Write` implementation, but could make that `Copy`
+#       and remove this dep with custom impl
+smallvec = { version = "1.15.0", features = ["write"] }
 
 document-features = { version = "0.2.0", optional = true }
 

gix-date/Cargo.toml

@@ -7,51 +7,28 @@
     doc = ::document_features::document_features!()
 )]
 #![cfg_attr(all(doc, feature = "document-features"), feature(doc_cfg, doc_auto_cfg))]
-#![deny(missing_docs, rust_2018_idioms)]
-#![forbid(unsafe_code)]
-
+#![deny(missing_docs, rust_2018_idioms, unsafe_code)]
 ///
 pub mod time;
 
 ///
 pub mod parse;
-use bstr::{BStr, ByteSlice};
 pub use parse::function::parse;
-pub use parse::function::parse_raw;
-use parse::Error;
-use std::time::SystemTime;
+pub use parse::function::parse_header;
 
 /// A timestamp with timezone.
 #[derive(PartialEq, Eq, Debug, Hash, Ord, PartialOrd, Clone, Copy)]
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 pub struct Time {
-    /// The seconds that passed since UNIX epoch. This makes it UTC, or `<seconds>+0000`.
+    /// The seconds that have passed since UNIX epoch. This makes it UTC, or `<seconds>+0000`.
     pub seconds: SecondsSinceUnixEpoch,
     /// The time's offset in seconds, which may be negative to match the `sign` field.
     pub offset: OffsetInSeconds,
     /// the sign of `offset`, used to encode `-0000` which would otherwise lose sign information.
     pub sign: time::Sign,
 }
 
-impl Time {
-    /// Parse date in config format into a Time
-    pub fn from_config(i: &BStr) -> Result<Self, Error> {
-        let s = i.as_bstr().to_str().expect("Input must be ascii");
-        parse(s, Some(SystemTime::now()))
-    }
-    /// Parse raw bytes into a Time
-    pub fn from_bytes(i: &BStr) -> Result<Self, Error> {
-        let s = i.as_bstr().to_str().expect("Input must be ascii");
-        parse_raw(s).ok_or(Error::InvalidDateString { input: s.into() })
-    }
-    /// Write time into buffer
-    pub fn to_ref<'a>(&self, buf: &'a mut Vec<u8>) -> &'a BStr {
-        self.write_to(buf).expect("write to memory cannot fail");
-        buf.as_bstr()
-    }
-}
-
-/// The amount of seconds since unix epoch.
+/// The number of seconds since unix epoch.
 ///
 /// Note that negative dates represent times before the unix epoch.
 ///

gix-date/src/lib.rs

@@ -1,3 +1,7 @@
+use crate::Time;
+use smallvec::SmallVec;
+use std::str::FromStr;
+
 #[derive(thiserror::Error, Debug, Clone)]
 #[allow(missing_docs)]
 pub enum Error {
@@ -11,6 +15,61 @@ pub enum Error {
     MissingCurrentTime,
 }
 
+/// A container for just enough bytes to hold the largest-possible [`time`](Time) instance.
+/// It's used in conjunction with
+#[derive(Default, Clone)]
+pub struct TimeBuf {
+    buf: SmallVec<[u8; Time::MAX.size()]>,
+}
+
+impl TimeBuf {
+    /// Represent this instance as standard string, serialized in a format compatible with
+    /// signature fields in Git commits, also known as anything parseable as [raw format](function::parse_header()).
+    pub fn as_str(&self) -> &str {
+        // SAFETY: We know that serialized times are pure ASCII, a subset of UTF-8.
+        //         `buf` and `len` are written only by time-serialization code.
+        let time_bytes = self.buf.as_slice();
+        #[allow(unsafe_code)]
+        unsafe {
+            std::str::from_utf8_unchecked(time_bytes)
+        }
+    }
+
+    /// Clear the previous content.
+    pub fn clear(&mut self) {
+        self.buf.clear();
+    }
+}
+
+impl std::io::Write for TimeBuf {
+    fn write(&mut self, buf: &[u8]) -> std::io::Result<usize> {
+        self.buf.write(buf)
+    }
+
+    fn flush(&mut self) -> std::io::Result<()> {
+        self.buf.flush()
+    }
+}
+
+impl Time {
+    /// Serialize this instance into `buf`, exactly as it would appear in the header of a Git commit,
+    /// and return `buf` as `&str` for easy consumption.
+    pub fn to_str<'a>(&self, buf: &'a mut TimeBuf) -> &'a str {
+        buf.clear();
+        self.write_to(buf)
+            .expect("write to memory of just the right size cannot fail");
+        buf.as_str()
+    }
+}
+
+impl FromStr for Time {
+    type Err = Error;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        crate::parse_header(s).ok_or_else(|| Error::InvalidDateString { input: s.into() })
+    }
+}
+
 pub(crate) mod function {
     use std::{str::FromStr, time::SystemTime};
 
@@ -25,7 +84,67 @@ pub(crate) mod function {
         SecondsSinceUnixEpoch, Time,
     };
 
-    #[allow(missing_docs)]
+    /// Parse `input` as any time that Git can parse when inputting a date.
+    ///
+    /// ## Examples
+    ///
+    /// ### 1. SHORT Format
+    ///
+    /// *   `2018-12-24`
+    /// *   `1970-01-01`
+    /// *   `1950-12-31`
+    /// *   `2024-12-31`
+    ///
+    /// ### 2. RFC2822 Format
+    ///
+    /// *   `Thu, 18 Aug 2022 12:45:06 +0800`
+    /// *   `Mon Oct 27 10:30:00 2023 -0800`
+    ///
+    /// ### 3. GIT_RFC2822 Format
+    ///
+    /// *   `Thu, 8 Aug 2022 12:45:06 +0800`
+    /// *   `Mon Oct 27 10:30:00 2023 -0800` (Note the single-digit day)
+    ///
+    /// ### 4. ISO8601 Format
+    ///
+    /// *   `2022-08-17 22:04:58 +0200`
+    /// *   `1970-01-01 00:00:00 -0500`
+    ///
+    /// ### 5. ISO8601_STRICT Format
+    ///
+    /// *   `2022-08-17T21:43:13+08:00`
+    ///
+    /// ### 6. UNIX Timestamp (Seconds Since Epoch)
+    ///
+    /// *   `123456789`
+    /// *   `0` (January 1, 1970 UTC)
+    /// *   `-1000`
+    /// *   `1700000000`
+    ///
+    /// ### 7. Commit Header Format
+    ///
+    /// *   `1745582210 +0200`
+    /// *   `1660874655 +0800`
+    /// *   `-1660874655 +0800`
+    ///
+    /// See also the [`parse_header()`].
+    ///
+    /// ### 8. GITOXIDE Format
+    ///
+    /// *   `Thu Sep 04 2022 10:45:06 -0400`
+    /// *   `Mon Oct 27 2023 10:30:00 +0000`
+    ///
+    /// ### 9. DEFAULT Format
+    ///
+    /// *   `Thu Sep 4 10:45:06 2022 -0400`
+    /// *   `Mon Oct 27 10:30:00 2023 +0000`
+    ///
+    /// ### 10. Relative Dates (e.g., "2 minutes ago", "1 hour from now")
+    ///
+    /// These dates are parsed *relative to a `now` timestamp*. The examples depend entirely on the value of `now`.
+    /// If `now` is October 27, 2023 at 10:00:00 UTC:
+    ///     *   `2 minutes ago` (October 27, 2023 at 09:58:00 UTC)
+    ///     *   `3 hours ago` (October 27, 2023 at 07:00:00 UTC)
     pub fn parse(input: &str, now: Option<SystemTime>) -> Result<Time, Error> {
         // TODO: actual implementation, this is just to not constantly fail
         if input == "1979-02-26 18:30:00" {
@@ -50,7 +169,7 @@ pub(crate) mod function {
         } else if let Ok(val) = SecondsSinceUnixEpoch::from_str(input) {
             // Format::Unix
             Time::new(val, 0)
-        } else if let Some(val) = parse_raw(input) {
+        } else if let Some(val) = parse_header(input) {
             // Format::Raw
             val
         } else if let Some(val) = relative::parse(input, now).transpose()? {
@@ -60,8 +179,9 @@ pub(crate) mod function {
         })
     }
 
-    #[allow(missing_docs)]
-    pub fn parse_raw(input: &str) -> Option<Time> {
+    /// Unlike [`parse()`] which handles all kinds of input, this function only parses the commit-header format
+    /// like `1745582210 +0200`.
+    pub fn parse_header(input: &str) -> Option<Time> {
         let mut split = input.split_whitespace();
         let seconds: SecondsSinceUnixEpoch = split.next()?.parse().ok()?;
         let offset = split.next()?;

gix-date/src/parse.rs

@@ -44,7 +44,7 @@ impl Time {
         match format {
             Format::Custom(CustomFormat(format)) => self.to_time().strftime(format).to_string(),
             Format::Unix => self.seconds.to_string(),
-            Format::Raw => self.to_bstring().to_string(),
+            Format::Raw => self.to_string(),
         }
     }
 }