Fully implement the transition

Author: Ezrashaw

src/fmt/chrono/extern_impl.rs

@@ -1,9 +1,8 @@
-use std::fmt::{self, write};
-use std::time::SystemTime;
+use std::fmt;
 
 use chrono::{DateTime, SecondsFormat, Utc};
 
-use crate::fmt::{Formatter, TimestampPrecision};
+use crate::fmt::{Formatter, TimestampFormat, TimestampPrecision};
 
 pub(in crate::fmt) mod glob {
     pub use super::*;
@@ -32,57 +31,55 @@ impl Formatter {
     pub fn timestamp(&self) -> Timestamp {
         Timestamp {
             time: Utc::now(),
-            precision: TimestampPrecision::Seconds,
+            precision: Default::default(),
+            format: Default::default(),
         }
     }
 
-    /// Get a [`Timestamp`] for the current date and time in UTC with full
-    /// second precision.
-    pub fn timestamp_seconds(&self) -> Timestamp {
-        Timestamp {
-            time: Utc::now(),
-            precision: TimestampPrecision::Seconds,
-        }
-    }
-
-    /// Get a [`Timestamp`] for the current date and time in UTC with
-    /// millisecond precision.
-    pub fn timestamp_millis(&self) -> Timestamp {
-        Timestamp {
-            time: Utc::now(),
-            precision: TimestampPrecision::Millis,
-        }
-    }
-
-    /// Get a [`Timestamp`] for the current date and time in UTC with
-    /// microsecond precision.
-    pub fn timestamp_micros(&self) -> Timestamp {
-        Timestamp {
-            time: Utc::now(),
-            precision: TimestampPrecision::Micros,
-        }
-    }
-
-    /// Get a [`Timestamp`] for the current date and time in UTC with
-    /// nanosecond precision.
-    pub fn timestamp_nanos(&self) -> Timestamp {
+    /// Get a [`Timestamp`] for the current date and time in UTC with a specified style and precision.
+    ///
+    /// # Examples
+    ///
+    /// Include the current timestamp, in a 12-hour format to second precision, with the log record:
+    ///
+    /// ```
+    /// use std::io::Write;
+    /// use env_logger::fmt;
+    ///
+    /// let mut builder = env_logger::Builder::new();
+    ///
+    /// builder.format(|buf, record| {
+    ///     let ts = buf.timestamp_custom(fmt::TimestampPrecision::Seconds, fmt::TimestampFormat::Human12Hour);
+    ///
+    ///     writeln!(buf, "{}: {}: {}", ts, record.level(), record.args())
+    /// });
+    /// ```
+    ///
+    /// [`Timestamp`]: struct.Timestamp.html
+    pub fn timestamp_custom(
+        &self,
+        precision: TimestampPrecision,
+        format: TimestampFormat,
+    ) -> Timestamp {
         Timestamp {
             time: Utc::now(),
-            precision: TimestampPrecision::Nanos,
+            precision,
+            format,
         }
     }
 }
 
-/// An [RFC3339] formatted timestamp.
+/// An formatted timestamp.
 ///
-/// The timestamp implements [`Display`] and can be written to a [`Formatter`].
+/// The timestamp implements [`Display`] and can be written to a [`Formatter`]. This defaults to formatting with [RFC3339] with second precision.
 ///
 /// [RFC3339]: https://www.ietf.org/rfc/rfc3339.txt
 /// [`Display`]: https://doc.rust-lang.org/stable/std/fmt/trait.Display.html
 /// [`Formatter`]: struct.Formatter.html
 pub struct Timestamp {
     time: DateTime<Utc>,
     precision: TimestampPrecision,
+    format: TimestampFormat,
 }
 
 impl fmt::Debug for Timestamp {
@@ -104,16 +101,33 @@ impl fmt::Debug for Timestamp {
 
 impl fmt::Display for Timestamp {
     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
-        self.time
-            .to_rfc3339_opts(
-                match self.precision {
-                    TimestampPrecision::Seconds => SecondsFormat::Secs,
-                    TimestampPrecision::Millis => SecondsFormat::Millis,
-                    TimestampPrecision::Micros => SecondsFormat::Micros,
-                    TimestampPrecision::Nanos => SecondsFormat::Nanos,
-                },
-                true,
-            )
-            .fmt(f)
+        match self.format {
+            TimestampFormat::RFC3339 => self
+                .time
+                .to_rfc3339_opts(
+                    match self.precision {
+                        TimestampPrecision::Seconds => SecondsFormat::Secs,
+                        TimestampPrecision::Millis => SecondsFormat::Millis,
+                        TimestampPrecision::Micros => SecondsFormat::Micros,
+                        TimestampPrecision::Nanos => SecondsFormat::Nanos,
+                    },
+                    true,
+                )
+                .fmt(f),
+            TimestampFormat::Human12Hour => {
+                if self.precision != TimestampPrecision::Seconds {
+                    panic!("Sorry, currently with the new human timestamp formats, we only support second precision.");
+                }
+
+                self.time.format("%v %p").fmt(f)
+            }
+            TimestampFormat::Human24Hour => {
+                if self.precision != TimestampPrecision::Seconds {
+                    panic!("Sorry, currently with the new human timestamp formats, we only support second precision.");
+                }
+
+                self.time.format("%v %X").fmt(f)
+            }
+        }
     }
 }

src/fmt/mod.rs

@@ -54,7 +54,7 @@ pub(crate) mod glob {
 /// Seconds give precision of full seconds, milliseconds give thousands of a
 /// second (3 decimal digits), microseconds are millionth of a second (6 decimal
 /// digits) and nanoseconds are billionth of a second (9 decimal digits).
-#[derive(Copy, Clone, Debug)]
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
 pub enum TimestampPrecision {
     /// Full second precision (0 decimal digits)
     Seconds,
@@ -73,6 +73,52 @@ impl Default for TimestampPrecision {
     }
 }
 
+/// Standard used for formatting of timestamps.
+///
+/// RFC339 is the default and is a widely used internet standard, however it is not particularly human-readable.
+/// Currently, we also support human-readable formats with either a 12 or 24 hour clock. Note that this currently only works with `TimestampPrecision::Seconds`.
+#[derive(Copy, Clone, Debug, PartialEq, Eq)]
+pub enum TimestampFormat {
+    /// Full RFC3339 conformance
+    RFC3339,
+    /// A human-readable standard of the form "YYYY:MM:DD HH:MM:SS AM/PM".
+    Human12Hour,
+    /// A human-readable standard of the form "YYYY:MM:DD HH:MM:SS"
+    Human24Hour,
+}
+
+/// The default timestamp style is the RFC3339 standard.
+impl Default for TimestampFormat {
+    fn default() -> Self {
+        TimestampFormat::RFC3339
+    }
+}
+
+/// A styled timestamp, with precision and formatting.
+///
+/// Defaults to `TimestampFormat::RFC3339` and `TimestampPrecision::Seconds`.
+#[derive(Copy, Clone, Debug, PartialEq, Eq, Default)]
+pub struct TimestampStyle {
+    /// The format used for this style.
+    ///
+    /// Determines how the timestamp is displayed. E.G. HH:MM:SS or YY:MM:DD
+    pub format: TimestampFormat,
+
+    /// The precision used for this style.
+    ///
+    /// Determines how accurate the displayed timestamp is.
+    pub precision: TimestampPrecision,
+}
+
+impl TimestampStyle {
+    /// Create a new `TimestampStyle` from a format and precision.
+    ///
+    /// Rust's constructors can also be used instead of this method.
+    pub fn new(format: TimestampFormat, precision: TimestampPrecision) -> Self {
+        Self { format, precision }
+    }
+}
+
 /// A formatter to write logs into.
 ///
 /// `Formatter` implements the standard [`Write`] trait for writing log records.
@@ -139,7 +185,7 @@ impl fmt::Debug for Formatter {
 pub(crate) type FormatFn = Box<dyn Fn(&mut Formatter, &Record) -> io::Result<()> + Sync + Send>;
 
 pub(crate) struct Builder {
-    pub format_timestamp: Option<TimestampPrecision>,
+    pub format_timestamp: Option<TimestampStyle>,
     pub format_module_path: bool,
     pub format_target: bool,
     pub format_level: bool,
@@ -211,7 +257,7 @@ type SubtleStyle = &'static str;
 ///
 /// This format needs to work with any combination of crate features.
 struct DefaultFormat<'a> {
-    timestamp: Option<TimestampPrecision>,
+    timestamp: Option<TimestampStyle>,
     module_path: bool,
     target: bool,
     level: bool,
@@ -284,13 +330,12 @@ impl<'a> DefaultFormat<'a> {
     fn write_timestamp(&mut self) -> io::Result<()> {
         #[cfg(feature = "chrono")]
         {
-            use self::TimestampPrecision::*;
-            let ts = match self.timestamp {
-                None => return Ok(()),
-                Some(Seconds) => self.buf.timestamp_seconds(),
-                Some(Millis) => self.buf.timestamp_millis(),
-                Some(Micros) => self.buf.timestamp_micros(),
-                Some(Nanos) => self.buf.timestamp_nanos(),
+            // Make sure that timestamp is defined, otherwise omit writing the timestamp.
+            let ts = if let Some(timestamp) = self.timestamp {
+                self.buf
+                    .timestamp_custom(timestamp.precision, timestamp.format)
+            } else {
+                return Ok(());
             };
 
             self.write_header_value(ts)

src/lib.rs

@@ -286,6 +286,7 @@
 
 use std::{borrow::Cow, cell::RefCell, env, io};
 
+use fmt::TimestampFormat;
 use log::{LevelFilter, Log, Metadata, Record, SetLoggerError};
 
 pub mod filter;
@@ -617,30 +618,58 @@ impl Builder {
         self
     }
 
-    /// Configures if timestamp should be included and in what precision.
-    pub fn format_timestamp(&mut self, timestamp: Option<fmt::TimestampPrecision>) -> &mut Self {
-        self.format.format_timestamp = timestamp;
+    /// Configures if timestamp should be included and in what precision and style.
+    pub fn format_timestamp(&mut self, style: Option<fmt::TimestampStyle>) -> &mut Self {
+        self.format.format_timestamp = style;
         self
     }
 
     /// Configures the timestamp to use second precision.
     pub fn format_timestamp_secs(&mut self) -> &mut Self {
-        self.format_timestamp(Some(fmt::TimestampPrecision::Seconds))
+        self.format_timestamp(Some(fmt::TimestampStyle::new(
+            TimestampFormat::default(),
+            TimestampPrecision::Seconds,
+        )))
     }
 
     /// Configures the timestamp to use millisecond precision.
     pub fn format_timestamp_millis(&mut self) -> &mut Self {
-        self.format_timestamp(Some(fmt::TimestampPrecision::Millis))
+        self.format_timestamp(Some(fmt::TimestampStyle::new(
+            TimestampFormat::default(),
+            TimestampPrecision::Millis,
+        )))
     }
 
     /// Configures the timestamp to use microsecond precision.
     pub fn format_timestamp_micros(&mut self) -> &mut Self {
-        self.format_timestamp(Some(fmt::TimestampPrecision::Micros))
+        self.format_timestamp(Some(fmt::TimestampStyle::new(
+            TimestampFormat::default(),
+            TimestampPrecision::Micros,
+        )))
     }
 
     /// Configures the timestamp to use nanosecond precision.
     pub fn format_timestamp_nanos(&mut self) -> &mut Self {
-        self.format_timestamp(Some(fmt::TimestampPrecision::Nanos))
+        self.format_timestamp(Some(fmt::TimestampStyle::new(
+            TimestampFormat::default(),
+            TimestampPrecision::Nanos,
+        )))
+    }
+
+    /// Configures the timestamp to use second precision, formatted as a 12-hour clock.
+    pub fn format_timestamp_12hour(&mut self) -> &mut Self {
+        self.format_timestamp(Some(fmt::TimestampStyle::new(
+            TimestampFormat::Human12Hour,
+            TimestampPrecision::Seconds,
+        )))
+    }
+
+    /// Configures the timestamp to use second precision, formatted as a 24-hour clock.
+    pub fn format_timestamp_24hour(&mut self) -> &mut Self {
+        self.format_timestamp(Some(fmt::TimestampStyle::new(
+            TimestampFormat::Human24Hour,
+            TimestampPrecision::Seconds,
+        )))
     }
 
     /// Configures the end of line suffix.