objc2_foundation/
range.rs

1use core::ops::Range;
2
3use objc2::encode::{Encode, Encoding, RefEncode};
4
5use crate::NSUInteger;
6
7/// TODO.
8///
9/// See [Apple's documentation](https://developer.apple.com/documentation/foundation/nsrange?language=objc).
10#[repr(C)]
11// PartialEq is same as NSEqualRanges
12#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash, PartialOrd, Ord)]
13pub struct NSRange {
14    /// The lower bound of the range (inclusive).
15    pub location: NSUInteger,
16    /// The number of items in the range, starting from `location`.
17    pub length: NSUInteger,
18}
19
20impl NSRange {
21    /// Create a new range with the given values.
22    ///
23    /// # Examples
24    ///
25    /// ```
26    /// use objc2_foundation::NSRange;
27    /// assert_eq!(NSRange::new(3, 2), NSRange::from(3..5));
28    /// ```
29    #[inline]
30    #[doc(alias = "NSMakeRange")]
31    pub const fn new(location: usize, length: usize) -> Self {
32        // Equivalent to NSMakeRange
33        Self { location, length }
34    }
35
36    /// Returns `true` if the range contains no items.
37    ///
38    /// # Examples
39    ///
40    /// ```
41    /// use objc2_foundation::NSRange;
42    ///
43    /// assert!(!NSRange::from(3..5).is_empty());
44    /// assert!( NSRange::from(3..3).is_empty());
45    /// ```
46    #[inline]
47    pub fn is_empty(&self) -> bool {
48        self.length == 0
49    }
50
51    /// Returns `true` if the index is within the range.
52    ///
53    /// # Examples
54    ///
55    /// ```
56    /// use objc2_foundation::NSRange;
57    ///
58    /// assert!(!NSRange::from(3..5).contains(2));
59    /// assert!( NSRange::from(3..5).contains(3));
60    /// assert!( NSRange::from(3..5).contains(4));
61    /// assert!(!NSRange::from(3..5).contains(5));
62    ///
63    /// assert!(!NSRange::from(3..3).contains(3));
64    /// ```
65    #[inline]
66    #[doc(alias = "NSLocationInRange")]
67    pub fn contains(&self, index: usize) -> bool {
68        // Same as NSLocationInRange
69        if let Some(len) = index.checked_sub(self.location) {
70            len < self.length
71        } else {
72            // index < self.location
73            false
74        }
75    }
76
77    /// Returns the upper bound of the range (exclusive).
78    #[inline]
79    #[doc(alias = "NSMaxRange")]
80    pub fn end(&self) -> usize {
81        self.location
82            .checked_add(self.length)
83            .expect("NSRange too large")
84    }
85
86    // TODO: https://developer.apple.com/documentation/foundation/1408420-nsrangefromstring
87    // TODO: NSUnionRange
88    // TODO: NSIntersectionRange
89}
90
91// Sadly, we can't do this:
92// impl RangeBounds<usize> for NSRange {
93//     fn start_bound(&self) -> Bound<&usize> {
94//         Bound::Included(&self.location)
95//     }
96//     fn end_bound(&self) -> Bound<&usize> {
97//         Bound::Excluded(&(self.location + self.length))
98//     }
99// }
100
101impl From<Range<usize>> for NSRange {
102    fn from(range: Range<usize>) -> Self {
103        let length = range
104            .end
105            .checked_sub(range.start)
106            .expect("Range end < start");
107        Self {
108            location: range.start,
109            length,
110        }
111    }
112}
113
114impl From<NSRange> for Range<usize> {
115    #[inline]
116    fn from(nsrange: NSRange) -> Self {
117        Self {
118            start: nsrange.location,
119            end: nsrange.end(),
120        }
121    }
122}
123
124unsafe impl Encode for NSRange {
125    const ENCODING: Encoding = Encoding::Struct("_NSRange", &[usize::ENCODING, usize::ENCODING]);
126}
127
128unsafe impl RefEncode for NSRange {
129    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
130}
131
132#[cfg(test)]
133mod tests {
134    use super::*;
135
136    #[test]
137    fn test_from_range() {
138        let cases: &[(Range<usize>, NSRange)] = &[
139            (0..0, NSRange::new(0, 0)),
140            (0..10, NSRange::new(0, 10)),
141            (10..10, NSRange::new(10, 0)),
142            (10..20, NSRange::new(10, 10)),
143        ];
144
145        for (range, expected) in cases {
146            assert_eq!(NSRange::from(range.clone()), *expected);
147        }
148    }
149
150    #[test]
151    #[should_panic = "Range end < start"]
152    #[allow(clippy::reversed_empty_ranges)]
153    fn test_from_range_inverted() {
154        let _ = NSRange::from(10..0);
155    }
156
157    #[test]
158    fn test_contains() {
159        let range = NSRange::from(10..20);
160        assert!(!range.contains(0));
161        assert!(!range.contains(9));
162        assert!(range.contains(10));
163        assert!(range.contains(11));
164        assert!(!range.contains(20));
165        assert!(!range.contains(21));
166    }
167
168    #[test]
169    fn test_end() {
170        let range = NSRange::from(10..20);
171        assert!(!range.contains(0));
172        assert!(!range.contains(9));
173        assert!(range.contains(10));
174        assert!(range.contains(11));
175        assert!(!range.contains(20));
176        assert!(!range.contains(21));
177    }
178
179    #[test]
180    #[should_panic = "NSRange too large"]
181    fn test_end_large() {
182        let _ = NSRange::new(usize::MAX, usize::MAX).end();
183    }
184}
objc2_foundation/range.rs

objc2_foundation/
range.rs
