use core::fmt;
use core::str::FromStr;
use serde::{Deserialize, Deserializer, Serialize, Serializer};
use time::OffsetDateTime;
use time::format_description::well_known::Rfc3339;
use super::validate::{Validate, Validator, ViolationCode};
#[derive(Clone, Debug)]
pub struct DateTime {
at: Option<OffsetDateTime>,
raw: String,
}
#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
#[error("{value:?} is not an RFC 3339 timestamp: {reason}")]
pub struct DateTimeError {
value: String,
reason: String,
}
impl DateTime {
pub fn new(value: impl Into<String>) -> Result<Self, DateTimeError> {
let raw = value.into();
match OffsetDateTime::parse(&raw, &Rfc3339) {
Ok(at) => Ok(Self { at: Some(at), raw }),
Err(e) => Err(DateTimeError { value: raw, reason: e.to_string() }),
}
}
#[must_use]
pub fn new_unchecked(value: impl Into<String>) -> Self {
let raw = value.into();
let at = OffsetDateTime::parse(&raw, &Rfc3339).ok();
Self { at, raw }
}
#[must_use]
pub fn from_offset(at: OffsetDateTime) -> Self {
let at = at.to_offset(time::UtcOffset::UTC);
let raw = at.format(&Rfc3339).unwrap_or_default();
Self { at: Some(at), raw }
}
#[must_use]
pub const fn as_offset(&self) -> Option<OffsetDateTime> {
self.at
}
#[must_use]
pub fn as_str(&self) -> &str {
&self.raw
}
#[must_use]
pub const fn is_well_formed(&self) -> bool {
self.at.is_some()
}
#[must_use]
pub fn now() -> Self {
Self::from_offset(OffsetDateTime::now_utc())
}
}
impl fmt::Display for DateTime {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(&self.raw)
}
}
impl PartialEq for DateTime {
fn eq(&self, other: &Self) -> bool {
match (self.at, other.at) {
(Some(a), Some(b)) => a == b,
_ => self.raw == other.raw,
}
}
}
impl Eq for DateTime {}
impl core::hash::Hash for DateTime {
fn hash<H: core::hash::Hasher>(&self, state: &mut H) {
match self.at {
Some(at) => at.hash(state),
None => self.raw.hash(state),
}
}
}
impl PartialOrd for DateTime {
fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> {
Some(self.cmp(other))
}
}
impl Ord for DateTime {
fn cmp(&self, other: &Self) -> core::cmp::Ordering {
match (self.at, other.at) {
(Some(a), Some(b)) => a.cmp(&b),
(Some(_), None) => core::cmp::Ordering::Less,
(None, Some(_)) => core::cmp::Ordering::Greater,
(None, None) => self.raw.cmp(&other.raw),
}
}
}
impl From<OffsetDateTime> for DateTime {
fn from(at: OffsetDateTime) -> Self {
Self::from_offset(at)
}
}
impl TryFrom<DateTime> for OffsetDateTime {
type Error = DateTimeError;
fn try_from(t: DateTime) -> Result<Self, Self::Error> {
t.at.ok_or(DateTimeError { value: t.raw, reason: "not an RFC 3339 timestamp".to_owned() })
}
}
impl FromStr for DateTime {
type Err = DateTimeError;
fn from_str(s: &str) -> Result<Self, Self::Err> {
Self::new(s)
}
}
impl Validate for DateTime {
fn validate_in(&self, v: &mut Validator) {
if self.at.is_none() {
v.report(ViolationCode::PatternMismatch, format!("{:?} is not an RFC 3339 timestamp", self.raw));
}
}
}
impl Serialize for DateTime {
fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
s.serialize_str(&self.raw)
}
}
impl<'de> Deserialize<'de> for DateTime {
fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
Ok(Self::new_unchecked(String::deserialize(d)?))
}
}
#[cfg(feature = "schema")]
impl schemars::JsonSchema for DateTime {
fn schema_name() -> std::borrow::Cow<'static, str> {
"DateTime".into()
}
fn json_schema(_g: &mut schemars::SchemaGenerator) -> schemars::Schema {
schemars::json_schema!({ "type": "string", "format": "date-time" })
}
}
#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct HourMinute(String);
impl HourMinute {
pub fn new(value: impl Into<String>) -> Result<Self, DateTimeError> {
let raw = value.into();
Self::check(&raw).map(|()| Self(raw))
}
#[must_use]
pub fn new_unchecked(value: impl Into<String>) -> Self {
Self(value.into())
}
pub fn from_hm(hour: u8, minute: u8) -> Result<Self, DateTimeError> {
Self::new(format!("{hour:02}:{minute:02}"))
}
#[must_use]
pub fn as_str(&self) -> &str {
&self.0
}
#[must_use]
pub fn minutes_of_day(&self) -> Option<u16> {
let (h, m) = self.0.split_once(':')?;
Some(u16::from(h.parse::<u8>().ok()?) * 60 + u16::from(m.parse::<u8>().ok()?))
}
#[must_use]
pub fn is_well_formed(&self) -> bool {
Self::check(&self.0).is_ok()
}
fn check(s: &str) -> Result<(), DateTimeError> {
let err = |reason: &str| DateTimeError { value: s.to_owned(), reason: reason.to_owned() };
let (h, m) = s.split_once(':').ok_or_else(|| err("expected HH:MM"))?;
if h.len() != 2 || m.len() != 2 || !h.bytes().chain(m.bytes()).all(|c| c.is_ascii_digit()) {
return Err(err("expected two digits, a colon and two digits"));
}
let hour: u8 = h.parse().map_err(|_| err("the hour is not a number"))?;
let minute: u8 = m.parse().map_err(|_| err("the minute is not a number"))?;
if hour > 24 || minute > 59 || (hour == 24 && minute != 0) {
return Err(err("the time is out of range"));
}
Ok(())
}
}
impl fmt::Display for HourMinute {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(&self.0)
}
}
impl FromStr for HourMinute {
type Err = DateTimeError;
fn from_str(s: &str) -> Result<Self, Self::Err> {
Self::new(s)
}
}
impl Validate for HourMinute {
fn validate_in(&self, v: &mut Validator) {
if let Err(e) = Self::check(&self.0) {
v.report(ViolationCode::PatternMismatch, e.to_string());
}
}
}
impl Serialize for HourMinute {
fn serialize<S: Serializer>(&self, s: S) -> Result<S::Ok, S::Error> {
s.serialize_str(&self.0)
}
}
impl<'de> Deserialize<'de> for HourMinute {
fn deserialize<D: Deserializer<'de>>(d: D) -> Result<Self, D::Error> {
Ok(Self::new_unchecked(String::deserialize(d)?))
}
}
#[cfg(feature = "schema")]
impl schemars::JsonSchema for HourMinute {
fn schema_name() -> std::borrow::Cow<'static, str> {
"HourMinute".into()
}
fn json_schema(_g: &mut schemars::SchemaGenerator) -> schemars::Schema {
schemars::json_schema!({ "type": "string", "pattern": "[0-9]{2}:[0-9]{2}" })
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn timestamps_are_written_back_exactly_as_they_arrived() {
for text in ["2020-09-23T14:17:53.038Z", "2018-01-23T14:04:29.377Z", "2021-01-23T14:21:36.954Z"] {
let t: DateTime = text.parse().unwrap();
assert_eq!(serde_json::to_string(&t).unwrap(), format!("\"{text}\""));
}
}
#[test]
fn an_offset_denotes_the_same_instant_as_its_utc_form() {
let utc: DateTime = "2020-09-23T14:17:53.038Z".parse().unwrap();
let offset: DateTime = "2020-09-23T16:17:53.038+02:00".parse().unwrap();
assert_eq!(utc, offset);
assert_eq!(offset.to_string(), "2020-09-23T16:17:53.038+02:00");
}
#[test]
fn a_malformed_timestamp_decodes_and_is_reported() {
let t: DateTime = serde_json::from_str(r#""23.09.2020 14:17""#).unwrap();
assert!(!t.is_well_formed());
assert_eq!(t.validate().unwrap_err().as_slice()[0].code, ViolationCode::PatternMismatch);
assert_eq!(serde_json::to_string(&t).unwrap(), r#""23.09.2020 14:17""#);
}
#[test]
fn hour_minute_checks_the_pattern_and_the_range() {
for good in ["08:30", "00:00", "23:59", "24:00"] {
let value: HourMinute = good.parse().unwrap_or_else(|e| panic!("{good}: {e}"));
assert_eq!(value.as_str(), good, "the text is kept");
assert_eq!(value.to_string(), good);
assert!(value.is_well_formed());
assert!(value.validate().is_ok());
}
assert_eq!("08:30".parse::<HourMinute>().unwrap().minutes_of_day(), Some(510));
assert_eq!("24:00".parse::<HourMinute>().unwrap().minutes_of_day(), Some(1440));
for bad in ["8:30", "0830", "25:00", "08:60", "24:01", "", "0a:30"] {
assert!(bad.parse::<HourMinute>().is_err(), "{bad} should be rejected");
let arrived = HourMinute::new_unchecked(bad);
assert!(!arrived.is_well_formed(), "{bad}");
assert!(arrived.validate().is_err(), "{bad} decodes but must be reported");
assert_eq!(arrived.as_str(), bad, "and its text survives");
}
}
#[test]
fn equality_hashing_and_ordering_agree_with_each_other() {
use std::hash::{BuildHasher as _, RandomState};
let hasher = RandomState::new();
let utc: DateTime = "2020-09-23T14:17:53.038Z".parse().unwrap();
let offset: DateTime = "2020-09-23T16:17:53.038+02:00".parse().unwrap();
let later: DateTime = "2020-09-23T14:17:53.039Z".parse().unwrap();
let junk_a = DateTime::new_unchecked("23.09.2020");
let junk_b = DateTime::new_unchecked("nope");
assert_eq!(utc, offset);
assert_eq!(hasher.hash_one(&utc), hasher.hash_one(&offset));
assert_eq!(utc.cmp(&offset), core::cmp::Ordering::Equal);
assert_ne!(utc, later);
assert!(utc < later);
assert_ne!(hasher.hash_one(&utc), hasher.hash_one(&later));
assert_ne!(junk_a, junk_b);
assert_ne!(junk_a.cmp(&junk_b), core::cmp::Ordering::Equal);
assert_eq!(junk_a, DateTime::new_unchecked("23.09.2020"));
assert_eq!(hasher.hash_one(&junk_a), hasher.hash_one(DateTime::new_unchecked("23.09.2020")));
assert_ne!(hasher.hash_one(&junk_a), hasher.hash_one(&junk_b));
assert_ne!(utc, junk_a);
assert!(utc < junk_a);
let all = [&utc, &offset, &later, &junk_a, &junk_b];
for a in all {
for b in all {
assert_eq!(
a.cmp(b) == core::cmp::Ordering::Equal,
a == b,
"Ord and Eq disagree on {a} vs {b}"
);
}
}
}
#[cfg(feature = "schema")]
#[test]
fn the_published_schema_says_what_these_types_are_on_the_wire() {
let mut generator = schemars::SchemaGenerator::default();
let timestamp = <DateTime as schemars::JsonSchema>::json_schema(&mut generator);
let json = serde_json::to_value(×tamp).unwrap();
assert_eq!(json["type"], "string");
assert_eq!(json["format"], "date-time");
let hour_minute = <HourMinute as schemars::JsonSchema>::json_schema(&mut generator);
let json = serde_json::to_value(&hour_minute).unwrap();
assert_eq!(json["type"], "string");
assert_eq!(json["pattern"], "[0-9]{2}:[0-9]{2}");
}
#[test]
fn an_unreadable_timestamp_has_no_instant() {
let broken = DateTime::new_unchecked("23.09.2020 14:17");
assert_eq!(broken.as_offset(), None, "and does not silently read as the epoch");
assert!(OffsetDateTime::try_from(broken).is_err());
let good: DateTime = "2020-09-23T14:17:53.038Z".parse().unwrap();
assert!(good.as_offset().is_some());
}
}