Add PartiaEq, remove equals method, and add docs

Author: nekevss

Diff for: src/builtins/core/date.rs

@@ -127,7 +127,7 @@ macro_rules! impl_with_fallback_method {
 
 /// The native Rust implementation of `Temporal.PlainDate`.
 #[non_exhaustive]
-#[derive(Debug, Default, Clone)]
+#[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct PlainDate {
     pub(crate) iso: IsoDate,
     calendar: Calendar,
@@ -435,15 +435,17 @@ impl PlainDate {
         other.iso.to_epoch_days() - self.iso.to_epoch_days()
     }
 
+    /// Compares one `PlainDate` to another `PlainDate` using their
+    /// `IsoDate` representation.
+    ///
+    /// # Note on Ordering.
+    ///
+    /// `temporal_rs` does not implement `PartialOrd`/`Ord` as `PlainDate` does
+    /// not fulfill all the conditions required to implement the traits. However,
+    /// it is possible to compare `PlainDate`'s as their `IsoDate` representation.
     #[inline]
     #[must_use]
-    pub fn equals(&self, other: &Self) -> bool {
-        self.compare(other) == Ordering::Equal && self.calendar == other.calendar
-    }
-
-    #[inline]
-    #[must_use]
-    pub fn compare(&self, other: &Self) -> Ordering {
+    pub fn compare_iso(&self, other: &Self) -> Ordering {
         self.iso.cmp(&other.iso)
     }
 
@@ -640,25 +642,31 @@ mod tests {
         assert!(err.is_err());
         let err = PlainDate::try_new(275_760, 9, 14, Calendar::default());
         assert!(err.is_err());
-        let ok = PlainDate::try_new(-271_821, 4, 19, Calendar::default()).unwrap();
-        assert!(ok.equals(&PlainDate {
-            iso: IsoDate {
-                year: -271_821,
-                month: 4,
-                day: 19,
-            },
-            calendar: Calendar::default(),
-        }));
-
-        let ok = PlainDate::try_new(275_760, 9, 13, Calendar::default()).unwrap();
-        assert!(ok.equals(&PlainDate {
-            iso: IsoDate {
-                year: 275760,
-                month: 9,
-                day: 13,
-            },
-            calendar: Calendar::default(),
-        }));
+        let ok = PlainDate::try_new(-271_821, 4, 19, Calendar::default());
+        assert_eq!(
+            ok,
+            Ok(PlainDate {
+                iso: IsoDate {
+                    year: -271_821,
+                    month: 4,
+                    day: 19,
+                },
+                calendar: Calendar::default(),
+            })
+        );
+
+        let ok = PlainDate::try_new(275_760, 9, 13, Calendar::default());
+        assert_eq!(
+            ok,
+            Ok(PlainDate {
+                iso: IsoDate {
+                    year: 275760,
+                    month: 9,
+                    day: 13,
+                },
+                calendar: Calendar::default(),
+            })
+        );
     }
 
     #[test]
@@ -710,30 +718,36 @@ mod tests {
         assert!(result.is_err());
 
         let max = PlainDate::try_new(275_760, 9, 12, Calendar::default()).unwrap();
-        let result = max.add(&Duration::from_str("P1D").unwrap(), None).unwrap();
-        assert!(result.equals(&PlainDate {
-            iso: IsoDate {
-                year: 275760,
-                month: 9,
-                day: 13
-            },
-            calendar: Calendar::default(),
-        }));
+        let result = max.add(&Duration::from_str("P1D").unwrap(), None);
+        assert_eq!(
+            result,
+            Ok(PlainDate {
+                iso: IsoDate {
+                    year: 275760,
+                    month: 9,
+                    day: 13
+                },
+                calendar: Calendar::default(),
+            })
+        );
 
         let min = PlainDate::try_new(-271_821, 4, 19, Calendar::default()).unwrap();
         let result = min.add(&Duration::from_str("-P1D").unwrap(), None);
         assert!(result.is_err());
 
         let min = PlainDate::try_new(-271_821, 4, 20, Calendar::default()).unwrap();
-        let result = min.add(&Duration::from_str("-P1D").unwrap(), None).unwrap();
-        assert!(result.equals(&PlainDate {
-            iso: IsoDate {
-                year: -271_821,
-                month: 4,
-                day: 19
-            },
-            calendar: Calendar::default(),
-        }));
+        let result = min.add(&Duration::from_str("-P1D").unwrap(), None);
+        assert_eq!(
+            result,
+            Ok(PlainDate {
+                iso: IsoDate {
+                    year: -271_821,
+                    month: 4,
+                    day: 19
+                },
+                calendar: Calendar::default(),
+            })
+        );
     }
 
     #[test]

Diff for: src/builtins/core/datetime.rs

@@ -30,7 +30,7 @@ pub struct PartialDateTime {
 
 /// The native Rust implementation of `Temporal.PlainDateTime`
 #[non_exhaustive]
-#[derive(Debug, Default, Clone)]
+#[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct PlainDateTime {
     pub(crate) iso: IsoDateTime,
     calendar: Calendar,
@@ -563,15 +563,17 @@ impl PlainDateTime {
 }
 
 impl PlainDateTime {
+    /// Compares one `PlainDateTime` to another `PlainDateTime` using their
+    /// `IsoDate` representation.
+    ///
+    /// # Note on Ordering.
+    ///
+    /// `temporal_rs` does not implement `PartialOrd`/`Ord` as `PlainDateTime` does
+    /// not fulfill all the conditions required to implement the traits. However,
+    /// it is possible to compare `PlainDate`'s as their `IsoDate` representation.
     #[inline]
     #[must_use]
-    pub fn equals(&self, other: &Self) -> bool {
-        self.compare(other) == Ordering::Equal && self.calendar == other.calendar
-    }
-
-    #[inline]
-    #[must_use]
-    pub fn compare(&self, other: &Self) -> Ordering {
+    pub fn compare_iso(&self, other: &Self) -> Ordering {
         self.iso.cmp(&other.iso)
     }
 
@@ -735,31 +737,37 @@ mod tests {
         assert!(negative_limit.is_err());
         let positive_limit = pdt_from_date(275_760, 9, 14);
         assert!(positive_limit.is_err());
-        let within_negative_limit = pdt_from_date(-271_821, 4, 20).unwrap();
-        assert!(within_negative_limit.equals(&PlainDateTime {
-            iso: IsoDateTime {
-                date: IsoDate {
-                    year: -271_821,
-                    month: 4,
-                    day: 20,
+        let within_negative_limit = pdt_from_date(-271_821, 4, 20);
+        assert_eq!(
+            within_negative_limit,
+            Ok(PlainDateTime {
+                iso: IsoDateTime {
+                    date: IsoDate {
+                        year: -271_821,
+                        month: 4,
+                        day: 20,
+                    },
+                    time: IsoTime::default(),
                 },
-                time: IsoTime::default(),
-            },
-            calendar: Calendar::default(),
-        }));
-
-        let within_positive_limit = pdt_from_date(275_760, 9, 13).unwrap();
-        assert!(within_positive_limit.equals(&PlainDateTime {
-            iso: IsoDateTime {
-                date: IsoDate {
-                    year: 275_760,
-                    month: 9,
-                    day: 13,
+                calendar: Calendar::default(),
+            })
+        );
+
+        let within_positive_limit = pdt_from_date(275_760, 9, 13);
+        assert_eq!(
+            within_positive_limit,
+            Ok(PlainDateTime {
+                iso: IsoDateTime {
+                    date: IsoDate {
+                        year: 275_760,
+                        month: 9,
+                        day: 13,
+                    },
+                    time: IsoTime::default(),
                 },
-                time: IsoTime::default(),
-            },
-            calendar: Calendar::default(),
-        }));
+                calendar: Calendar::default(),
+            })
+        );
     }
 
     #[test]

Diff for: src/builtins/core/month_day.rs

@@ -1,7 +1,7 @@
 //! This module implements `MonthDay` and any directly related algorithms.
 
 use alloc::string::String;
-use core::{cmp::Ordering, str::FromStr};
+use core::str::FromStr;
 
 use tinystr::TinyAsciiStr;
 
@@ -14,7 +14,7 @@ use crate::{
 
 /// The native Rust implementation of `Temporal.PlainMonthDay`
 #[non_exhaustive]
-#[derive(Debug, Default, Clone)]
+#[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct PlainMonthDay {
     pub iso: IsoDate,
     calendar: Calendar,
@@ -90,11 +90,6 @@ impl PlainMonthDay {
         self.calendar.month_code(&self.iso)
     }
 
-    #[inline]
-    pub fn equals(&self, other: &Self) -> bool {
-        self.iso.cmp(&other.iso) == Ordering::Equal && self.calendar == other.calendar
-    }
-
     pub fn to_ixdtf_string(&self, display_calendar: DisplayCalendar) -> String {
         let ixdtf = FormattableMonthDay {
             date: FormattableDate(self.iso_year(), self.iso_month(), self.iso.day),

Diff for: src/builtins/core/year_month.rs

@@ -17,7 +17,7 @@ use super::{Duration, PartialDate};
 
 /// The native Rust implementation of `Temporal.YearMonth`.
 #[non_exhaustive]
-#[derive(Debug, Default, Clone)]
+#[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct PlainYearMonth {
     pub(crate) iso: IsoDate,
     calendar: Calendar,
@@ -137,15 +137,17 @@ impl PlainYearMonth {
         self.calendar.identifier()
     }
 
+    /// Compares one `PlainYearMonth` to another `PlainYearMonth` using their
+    /// `IsoDate` representation.
+    ///
+    /// # Note on Ordering.
+    ///
+    /// `temporal_rs` does not implement `PartialOrd`/`Ord` as `PlainYearMonth` does
+    /// not fulfill all the conditions required to implement the traits. However,
+    /// it is possible to compare `PlainDate`'s as their `IsoDate` representation.
     #[inline]
     #[must_use]
-    pub fn equals(&self, other: &Self) -> bool {
-        self.compare(other) == Ordering::Equal && self.calendar == other.calendar
-    }
-
-    #[inline]
-    #[must_use]
-    pub fn compare(&self, other: &Self) -> Ordering {
+    pub fn compare_iso(&self, other: &Self) -> Ordering {
         self.iso.cmp(&other.iso)
     }
 

Diff for: src/builtins/core/zoneddatetime.rs

@@ -29,7 +29,7 @@ use crate::{
 };
 
 /// A struct representing a partial `ZonedDateTime`.
-#[derive(Debug, Default, Clone)]
+#[derive(Debug, Default, Clone, PartialEq)]
 pub struct PartialZonedDateTime {
     /// The `PartialDate` portion of a `PartialZonedDateTime`
     pub date: PartialDate,
@@ -43,7 +43,7 @@ pub struct PartialZonedDateTime {
 
 /// The native Rust implementation of `Temporal.ZonedDateTime`.
 #[non_exhaustive]
-#[derive(Debug, Clone, PartialEq)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub struct ZonedDateTime {
     instant: Instant,
     calendar: Calendar,
@@ -421,17 +421,17 @@ impl ZonedDateTime {
         Self::try_new(self.epoch_nanoseconds(), calendar, self.tz.clone())
     }
 
+    /// Compares one `ZonedDateTime` to another `ZonedDateTime` using their
+    /// `Instant` representation.
+    ///
+    /// # Note on Ordering.
+    ///
+    /// `temporal_rs` does not implement `PartialOrd`/`Ord` as `ZonedDateTime` does
+    /// not fulfill all the conditions required to implement the traits. However,
+    /// it is possible to compare `PlainDate`'s as their `IsoDate` representation.
     #[inline]
     #[must_use]
-    pub fn equals(&self, other: &Self) -> bool {
-        self.compare(other) == Ordering::Equal
-            && self.tz == other.tz
-            && self.calendar == other.calendar
-    }
-
-    #[inline]
-    #[must_use]
-    pub fn compare(&self, other: &Self) -> Ordering {
+    pub fn compare_instant(&self, other: &Self) -> Ordering {
         self.instant.cmp(&other.instant)
     }
 }