0.0.2: add element insert/remove, shrink_to_fit

Author: spearman

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "range-set"
-version = "0.0.1"
+version = "0.0.2"
 authors = ["Shane Pearman <[email protected]>"]
 license = "Apache-2.0"
 

README.md

@@ -1,10 +1,12 @@
 # `range-set`
 
-> Store a collection of contiguous `PrimInt` values as inclusive ranges using
-> generic `SmallVec` storage
+> Store collections of `PrimInt` values as inclusive ranges using generic
+> `SmallVec`-backed storage.
 
-This is useful when you want to process elements in order when they are not
-quite perfectly contiguous. Having a generic `smallvec::Array` parameter allows
+[Documentation](https://spearman.github.io/range-set/range_set/index.html)
+
+This is useful when you want to process elements in order but they are not
+perfectly contiguous. Having a generic `smallvec::Array` parameter allows
 choosing how many ranges will fit on the stack before spilling over onto the
 heap:
 
@@ -26,14 +28,44 @@ let v : Vec <u8> = s.iter().collect();
 assert_eq!(v, vec![0,1,2,3,4,5,6,7,8,9,10,11,12]);
 ```
 
+
 ## Usage
 
-TODO
+Inclusive ranges are an unstable Rust feature (as of `rustc` 1.24) so they must
+be enabled in the crate root:
+
+```rust
+#![feature(inclusive_range)]
+#![feature(inclusive_range_syntax)]
+
+extern crate range_set;
+```
 
-## Memory usage characteristics
+```rust
+  use range_set::RangeSet;
+  use std::ops::RangeInclusive;
+  let mut s = RangeSet::<[RangeInclusive <u32>; 2]>::from_ranges (vec![
+    1..=100,
+    500..=1000
+  ].into()).unwrap();
+  s.insert (200);
+  s.insert (400..=499);
+  assert_eq!(s, RangeSet::from_ranges (vec![
+    1..=100,
+    200..=200,
+    400..=1000
+  ].into()).unwrap());
+```
 
-The top-level `report` function will report byte sizes for various sizes of
-integers and array sizes. An program calling this function can be found in
+See `./examples/example.rs` and documentation for more examples.
+
+
+## Performance characteristics
+
+**Memory**
+
+The top-level `report` function will report byte sizes for various integers and
+array sizes. A program calling this function can be found in
 `./examples/example.rs`. Example output:
 
 ```
@@ -66,6 +98,12 @@ RangeSet report...
 ...RangeSet report
 ```
 
-As can be seen, using this for byte ranges is not a good idea since the minimum
-usage is 32 bytes which is enough to store the full range of 256 values as
-individual bits (32 * 8 = 256).
+As can be seen, using this type for `u8` (byte) ranges is not a good idea since
+the minimum usage is 32 bytes which is enough to store the full range of 256
+values as individual bits (32 * 8 = 256).
+
+
+**Time complexity**
+
+Since the ranges are stored in sorted order, binary search is used when
+inserting and removing values.

TODO

@@ -1,3 +1,4 @@
-- remove
-- merge
-- more set operations
+- set operations
+  - union
+  - intersection
+  - difference

examples/example.rs

@@ -20,13 +20,13 @@ fn main() {
 
   assert_eq!(s.insert_range (3..=12), Some (RangeSet::from (8..=10)));
   println!("s: {:?}", s);
-  assert!(!s.spilled());
+  assert!(s.spilled());
   let v : Vec <u8> = s.iter().collect();
   assert_eq!(v, vec![0,1,2,3,4,5,6,7,8,9,10,11,12]);
 
   assert_eq!(s.remove_range (0..=2), Some (RangeSet::from (0..=2)));
   println!("s: {:?}", s);
-  assert!(!s.spilled());
+  assert!(s.spilled());
   let v : Vec <u8> = s.iter().collect();
   assert_eq!(v, vec![3,4,5,6,7,8,9,10,11,12]);
 
@@ -51,15 +51,15 @@ fn main() {
 
   assert_eq!(s.remove_range (5..=20), Some (RangeSet::from (11..=12)));
   println!("s: {:?}", s);
-  // /!\ spilled status does not get reset here
-  //assert!(!s.spilled());
+  assert!(s.spilled());   // stays spilled
+  s.shrink_to_fit();      // manually un-spill
+  assert!(!s.spilled());  // no longer spilled
   let v : Vec <u8> = s.iter().collect();
   assert_eq!(v, vec![3,4]);
 
   assert_eq!(s.remove_range (0..=10), Some (RangeSet::from (3..=4)));
   println!("s: {:?}", s);
-  // /!\ spilled status does not get reset here
-  //assert!(!s.spilled());
+  assert!(!s.spilled());
   let v : Vec <u8> = s.iter().collect();
   assert_eq!(v, vec![]);
 }

src/lib.rs

@@ -16,7 +16,8 @@ pub use range_compare::{
 //  structs                                                                  //
 ///////////////////////////////////////////////////////////////////////////////
 
-/// A set of elements represented as a sorted list of inclusive ranges.
+/// A set of primitive integers represented as a sorted list of inclusive
+/// ranges.
 ///
 /// ```
 /// # #![feature(inclusive_range)]
@@ -39,9 +40,11 @@ pub use range_compare::{
 ///
 /// assert_eq!(s.insert_range (3..=12), Some (RangeSet::from (8..=10)));
 /// println!("s: {:?}", s);
-/// assert!(!s.spilled());
+/// assert!(s.spilled());  // once spilled, stays spilled
 /// let v : Vec <u32> = s.iter().collect();
 /// assert_eq!(v, vec![0,1,2,3,4,5,6,7,8,9,10,11,12]);
+/// s.shrink_to_fit();  // manually un-spill
+/// assert!(!s.spilled());
 /// # }
 /// ```
 #[derive(Clone,Debug,Eq,PartialEq)]
@@ -134,6 +137,11 @@ pub fn report() {
 //  impls                                                                    //
 ///////////////////////////////////////////////////////////////////////////////
 
+// the majority of the logic for modifying range sets are the insert_range and
+// remove_range methods
+//
+// there are some helper functions with additional logic such as the
+// binary_search functions
 impl <A, T> RangeSet <A> where
   A : smallvec::Array <Item=std::ops::RangeInclusive <T>>
     + Eq + std::fmt::Debug,
@@ -147,6 +155,15 @@ impl <A, T> RangeSet <A> where
     }
   }
 
+  /// New empty range set with the internal smallvec initialized with the given
+  /// initial capacity
+  #[inline]
+  pub fn with_capacity (capacity : usize) -> Self {
+    RangeSet {
+      ranges: smallvec::SmallVec::with_capacity (capacity)
+    }
+  }
+
   /// Returns a new range set if the given vector of ranges is valid
   /// (`valid_range_vec`)
   #[inline]
@@ -164,6 +181,78 @@ impl <A, T> RangeSet <A> where
     self.ranges.is_empty()
   }
 
+  /// Clears the range set
+  #[inline]
+  pub fn clear (&mut self) {
+    self.ranges.clear()
+  }
+
+  /// Converts into the internal smallvec
+  #[inline]
+  pub fn into_smallvec (self) -> smallvec::SmallVec <A> {
+    self.ranges
+  }
+
+  /// Insert a single element, returning true if it was successfully inserted
+  /// or else false if it was already present
+  ///
+  /// ```
+  /// # #![feature(inclusive_range)]
+  /// # #![feature(inclusive_range_syntax)]
+  /// # use range_set::RangeSet;
+  /// # use std::ops::RangeInclusive;
+  /// let mut s = RangeSet::<[RangeInclusive <u32>; 2]>::new();
+  /// assert!(s.insert (4));
+  /// assert_eq!(s, RangeSet::from (4..=4));
+  /// assert!(!s.insert (4));
+  /// assert_eq!(s, RangeSet::from (4..=4));
+  /// assert!(s.insert (5));
+  /// assert_eq!(s, RangeSet::from (4..=5));
+  /// assert!(s.insert (3));
+  /// assert_eq!(s, RangeSet::from (3..=5));
+  /// assert!(s.insert (10));
+  /// assert_eq!(s, RangeSet::from_ranges (vec![3..=5, 10..=10].into()).unwrap());
+  /// ```
+  pub fn insert (&mut self, element : T) -> bool {
+    if let Some (_) = self.insert_range (element..=element) {
+      false
+    } else {
+      true
+    }
+  }
+
+  /// Remove a single element, returning true if it was successfully removed
+  /// or else false if it was not present
+  ///
+  /// ```
+  /// # #![feature(inclusive_range)]
+  /// # #![feature(inclusive_range_syntax)]
+  /// # use range_set::RangeSet;
+  /// # use std::ops::RangeInclusive;
+  /// let mut s = RangeSet::<[RangeInclusive <u32>; 2]>::from (0..=5);
+  /// assert!(s.remove (1));
+  /// assert_eq!(s, RangeSet::from_ranges (vec![0..=0, 2..=5].into()).unwrap());
+  /// assert!(!s.remove (1));
+  /// assert_eq!(s, RangeSet::from_ranges (vec![0..=0, 2..=5].into()).unwrap());
+  /// assert!(s.remove (4));
+  /// assert_eq!(s, RangeSet::from_ranges (vec![0..=0, 2..=3, 5..=5].into()).unwrap());
+  /// assert!(s.remove (3));
+  /// assert_eq!(s, RangeSet::from_ranges (vec![0..=0, 2..=2, 5..=5].into()).unwrap());
+  /// assert!(s.remove (2));
+  /// assert_eq!(s, RangeSet::from_ranges (vec![0..=0, 5..=5].into()).unwrap());
+  /// assert!(s.remove (0));
+  /// assert_eq!(s, RangeSet::from (5..=5));
+  /// assert!(s.remove (5));
+  /// assert!(s.is_empty());
+  /// ```
+  pub fn remove (&mut self, element : T) -> bool {
+    if let Some (_) = self.remove_range (element..=element) {
+      true
+    } else {
+      false
+    }
+  }
+
   /// Returns the intersected values if the range is not disjoint
   /// with the curret range set.
   ///
@@ -194,13 +283,11 @@ impl <A, T> RangeSet <A> where
       // of the intersection of the given range and the existing range set
       (None, None) => {
         let isect = self.range_intersection (&range, 0..self.ranges.len());
-        self.ranges = {
-          let mut v = smallvec::SmallVec::new();
-          v.push (
-            std::cmp::min (range.start, self.ranges[0].start)..=
-            std::cmp::max (range.end,   self.ranges[self.ranges.len()-1].end));
-          v
-        };
+        let new_range =
+          std::cmp::min (range.start, self.ranges[0].start)..=
+          std::cmp::max (range.end,   self.ranges[self.ranges.len()-1].end);
+        self.ranges.clear();
+        self.ranges.push (new_range);
         if !isect.is_empty() {
           Some (isect)
         } else {
@@ -411,6 +498,12 @@ impl <A, T> RangeSet <A> where
     self.ranges.spilled()
   }
 
+  /// Calls `shrink_to_fit` on the underlying smallvec
+  #[inline]
+  pub fn shrink_to_fit (&mut self) {
+    self.ranges.shrink_to_fit()
+  }
+
   /// Insert helper function: search for the last range in self that is
   /// `LessThanAdjacent` or `LessThanProper` when compared with the given range
   fn binary_search_before (&self, range : &A::Item) -> Option <usize> {