Allow binary-searching an array of disjoint ranges

Author: matklad

CHANGELOG.md

@@ -1,8 +1,12 @@
 # Changelog
 
+## 1.1.0
+
+* add `TextRange::ordering` method
+
 ## 1.0.0 :tada:
 
-* the carate is renmaed to `text-size` from `text_unit`
+* the carate is renamed to `text-size` from `text_unit`
 
 Transition table:
 - `TextUnit::of_char(c)`                ⟹ `TextSize::of(c)`

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "text-size"
-version = "1.0.0"
+version = "1.1.0"
 edition = "2018"
 
 authors = [

src/range.rs

@@ -1,3 +1,5 @@
+use cmp::Ordering;
+
 use {
     crate::TextSize,
     std::{
@@ -294,6 +296,50 @@ impl TextRange {
             end: self.end.checked_sub(offset)?,
         })
     }
+
+    /// Relative order of the two ranges (overlapping ranges are considered
+    /// equal).
+    ///
+    ///
+    /// This is useful when, for example, binary searching an array of disjoint
+    /// ranges.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use text_size::*;
+    /// # use std::cmp::Ordering;
+    ///
+    /// let a = TextRange::new(0.into(), 3.into());
+    /// let b = TextRange::new(4.into(), 5.into());
+    /// assert_eq!(a.ordering(b), Ordering::Less);
+    ///
+    /// let a = TextRange::new(0.into(), 3.into());
+    /// let b = TextRange::new(3.into(), 5.into());
+    /// assert_eq!(a.ordering(b), Ordering::Less);
+    ///
+    /// let a = TextRange::new(0.into(), 3.into());
+    /// let b = TextRange::new(2.into(), 5.into());
+    /// assert_eq!(a.ordering(b), Ordering::Equal);
+    ///
+    /// let a = TextRange::new(0.into(), 3.into());
+    /// let b = TextRange::new(2.into(), 2.into());
+    /// assert_eq!(a.ordering(b), Ordering::Equal);
+    ///
+    /// let a = TextRange::new(2.into(), 3.into());
+    /// let b = TextRange::new(2.into(), 2.into());
+    /// assert_eq!(a.ordering(b), Ordering::Greater);
+    /// ```
+    #[inline]
+    pub fn ordering(self, other: TextRange) -> Ordering {
+        if self.end() <= other.start() {
+            Ordering::Less
+        } else if other.end() <= self.start() {
+            Ordering::Greater
+        } else {
+            Ordering::Equal
+        }
+    }
 }
 
 impl Index<TextRange> for str {