Improve NSRange and NSComparisonResult

With a few ideas from https://github.com/nvzqz/fruity

Author: madsmtm

objc2-foundation/CHANGELOG.md

@@ -11,8 +11,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
   `NSArray`, which derefs to `NSObject`, which derefs to `Object`.
 
   This allows more ergonomic usage.
-* Implement `PartialOrd` and `Ord` for `NSString`.
+* Implement `PartialOrd` and `Ord` for `NSString` and `NSRange`.
 * Added `NSString::has_prefix` and `NSString::has_suffix`.
+* Added `NSRange` methods `new`, `is_empty`, `contains` and `end`.
 
 ### Changed
 * **BREAKING**: Removed the following helper traits in favor of inherent

objc2-foundation/src/comparison_result.rs

@@ -2,15 +2,22 @@ use core::cmp::Ordering;
 
 use objc2::{Encode, Encoding, RefEncode};
 
+/// Constants that indicate sort order.
+///
+/// See [Apple's documentation](https://developer.apple.com/documentation/foundation/nscomparisonresult?language=objc).
 #[repr(isize)] // NSInteger
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
 pub enum NSComparisonResult {
+    /// The left operand is smaller than the right operand.
     Ascending = -1,
+    /// The two operands are equal.
     Same = 0,
+    /// The left operand is greater than the right operand.
     Descending = 1,
 }
 
 impl Default for NSComparisonResult {
+    #[inline]
     fn default() -> Self {
         Self::Same
     }
@@ -25,6 +32,7 @@ unsafe impl RefEncode for NSComparisonResult {
 }
 
 impl From<Ordering> for NSComparisonResult {
+    #[inline]
     fn from(order: Ordering) -> Self {
         match order {
             Ordering::Less => Self::Ascending,
@@ -35,6 +43,7 @@ impl From<Ordering> for NSComparisonResult {
 }
 
 impl From<NSComparisonResult> for Ordering {
+    #[inline]
     fn from(comparison_result: NSComparisonResult) -> Self {
         match comparison_result {
             NSComparisonResult::Ascending => Self::Less,

objc2-foundation/src/range.rs

@@ -2,21 +2,90 @@ use core::ops::Range;
 
 use objc2::{Encode, Encoding, RefEncode};
 
+/// TODO.
+///
+/// See [Apple's documentation](https://developer.apple.com/documentation/foundation/nsrange?language=objc).
 #[repr(C)]
 // PartialEq is same as NSEqualRanges
-#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, PartialOrd, Ord)]
 pub struct NSRange {
+    /// The lower bound of the range (inclusive).
+    // NSUInteger
     pub location: usize,
+    /// The number of items in the range, starting from `location`.
+    // NSUInteger
     pub length: usize,
 }
 
-// impl NSRange {
-//     pub fn contains(&self, index: usize) -> bool {
-//         // Same as NSLocationInRange
-//         <Self as RangeBounds<usize>>::contains(self, &index)
-//     }
-// }
+impl NSRange {
+    /// Create a new range with the given values.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use objc2_foundation::NSRange;
+    /// assert_eq!(NSRange::new(3, 2), NSRange::from(3..5));
+    /// ```
+    #[inline]
+    pub const fn new(location: usize, length: usize) -> Self {
+        // Equivalent to NSMakeRange
+        Self { location, length }
+    }
 
+    /// Returns `true` if the range contains no items.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use objc2_foundation::NSRange;
+    ///
+    /// assert!(!NSRange::from(3..5).is_empty());
+    /// assert!( NSRange::from(3..3).is_empty());
+    /// ```
+    #[inline]
+    pub fn is_empty(&self) -> bool {
+        self.length == 0
+    }
+
+    /// Returns `true` if the index is within the range.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use objc2_foundation::NSRange;
+    ///
+    /// assert!(!NSRange::from(3..5).contains(2));
+    /// assert!( NSRange::from(3..5).contains(3));
+    /// assert!( NSRange::from(3..5).contains(4));
+    /// assert!(!NSRange::from(3..5).contains(5));
+    ///
+    /// assert!(!NSRange::from(3..3).contains(3));
+    /// ```
+    #[inline]
+    pub fn contains(&self, index: usize) -> bool {
+        // Same as NSLocationInRange
+        if let Some(len) = index.checked_sub(self.location) {
+            len < self.length
+        } else {
+            // index < self.location
+            false
+        }
+    }
+
+    /// Returns the upper bound of the range (exclusive).
+    #[inline]
+    pub fn end(&self) -> usize {
+        self.location
+            .checked_add(self.length)
+            .expect("NSRange too large")
+    }
+
+    // TODO: https://developer.apple.com/documentation/foundation/1408420-nsrangefromstring
+    // TODO: NSUnionRange
+    // TODO: NSIntersectionRange
+}
+
+// Sadly, we can't do this:
 // impl RangeBounds<usize> for NSRange {
 //     fn start_bound(&self) -> Bound<&usize> {
 //         Bound::Included(&self.location)
@@ -40,10 +109,11 @@ impl From<Range<usize>> for NSRange {
 }
 
 impl From<NSRange> for Range<usize> {
+    #[inline]
     fn from(nsrange: NSRange) -> Self {
         Self {
             start: nsrange.location,
-            end: nsrange.location + nsrange.length,
+            end: nsrange.end(),
         }
     }
 }
@@ -56,3 +126,56 @@ unsafe impl Encode for NSRange {
 unsafe impl RefEncode for NSRange {
     const ENCODING_REF: Encoding<'static> = Encoding::Pointer(&Self::ENCODING);
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_from_range() {
+        let cases: &[(Range<usize>, NSRange)] = &[
+            (0..0, NSRange::new(0, 0)),
+            (0..10, NSRange::new(0, 10)),
+            (10..10, NSRange::new(10, 0)),
+            (10..20, NSRange::new(10, 10)),
+        ];
+
+        for (range, expected) in cases {
+            assert_eq!(NSRange::from(range.clone()), *expected);
+        }
+    }
+
+    #[test]
+    #[should_panic = "Range end < start"]
+    fn test_from_range_inverted() {
+        let _ = NSRange::from(10..0);
+    }
+
+    #[test]
+    fn test_contains() {
+        let range = NSRange::from(10..20);
+        assert!(!range.contains(0));
+        assert!(!range.contains(9));
+        assert!(range.contains(10));
+        assert!(range.contains(11));
+        assert!(!range.contains(20));
+        assert!(!range.contains(21));
+    }
+
+    #[test]
+    fn test_end() {
+        let range = NSRange::from(10..20);
+        assert!(!range.contains(0));
+        assert!(!range.contains(9));
+        assert!(range.contains(10));
+        assert!(range.contains(11));
+        assert!(!range.contains(20));
+        assert!(!range.contains(21));
+    }
+
+    #[test]
+    #[should_panic = "NSRange too large"]
+    fn test_end_large() {
+        let _ = NSRange::new(usize::MAX, usize::MAX).end();
+    }
+}