Add a RangeInclusive library with non-mutating iterators (theseus-os#977)

* The `core::ops::RangeInclusive` type has many problems:
  weird mutable iterator behavior, non-Clone/Copy,
  unexpected extra memory usage beyond the two bounds, etc.
  This crate implements a version of `RangeInclusive` that aims
  to address these problems with an API that offers a separate
  iterator type rather than implementing `Iterator` directly on the range.

* This will be used as the inner implementation for both
  `PageRange` and `FrameRange` in an upcoming PR.

Author: Ramla-I

libs/range_inclusive/.gitignore

@@ -0,0 +1,2 @@
+# Generated by Cargo
+/target/

libs/range_inclusive/Cargo.toml

@@ -0,0 +1,5 @@
+[package]
+authors = ["Ramla Ijaz <[email protected]>"]
+name = "range_inclusive"
+description = "An implementation of RangeInclusive with an iterator that doesn't mutate the range."
+version = "0.1.0"

libs/range_inclusive/src/lib.rs

@@ -0,0 +1,136 @@
+//! A `RangeInclusive` implementation that offers a separate iterator type.
+//!
+//! This `RangeInclusive` does not directly implement the `Iterator` trait,
+//! allowing one to iterate over a copy of the range without mutating the original range.
+//! This is accomplished by requiring that the generic type `Idx` implements `Clone`;
+//! in the future we can remove this trait bound by using references, though most users
+//! of a range type typically do so with numeric types that are cheap to copy/clone.
+//!
+//! All behavior except iteration matches that of `std::ops::RangeInclusive`.
+//! Due to the iterator behavior, there is no need to waste space tracking
+//! whether the range has been `exhausted`, meaning that this `RangeInclusive`
+//! is exactly the size of its two bounds.
+
+#![no_std]
+#![feature(step_trait)]
+
+#[cfg(test)]
+mod test;
+
+use core::iter::Step;
+use core::ops::{RangeBounds, Bound, Bound::Included};
+
+/// A range bounded inclusively below and above (`start..=end`).
+///
+/// The `RangeInclusive` `start..=end` contains all values with `x >= start`
+/// and `x <= end`. It is empty unless `start <= end`.
+///
+/// See the crate-level docs for more information.
+#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
+pub struct RangeInclusive<Idx: Clone + PartialOrd> {
+    pub(crate) start: Idx,
+    pub(crate) end: Idx
+}
+
+impl<Idx: Clone + PartialOrd> RangeInclusive<Idx> {
+    /// Creates a new inclusive range.
+    #[inline]
+    pub const fn new(start: Idx, end: Idx) -> Self {
+        Self{ start, end }
+    }
+
+    /// Returns the lower bound of the range (inclusive).
+    #[inline]
+    pub const fn start(&self) -> &Idx {
+        &self.start
+    }
+
+    /// Returns the upper bound of the range (inclusive).
+    #[inline]
+    pub const fn end(&self) -> &Idx {
+        &self.end
+    }
+
+    /// Destructures the `RangeInclusive` into (lower bound, upper (inclusive) bound).
+    #[inline]
+    pub fn into_inner(self) -> (Idx, Idx) {
+        (self.start, self.end)
+    }
+
+    /// Returns `true` if the range contains no items.
+    pub fn is_empty(&self) -> bool {
+        !(self.start <= self.end)
+    }
+
+    /// Returns an iterator with the same `start` and `end` values as the range.
+    pub fn iter(&self) -> RangeInclusiveIterator<Idx> {
+        RangeInclusiveIterator { current: self.start.clone(), end: self.end.clone() }
+    }
+
+    /// Returns `true` if `item` is contained in the range.
+    pub fn contains<U>(&self, item: &U) -> bool
+    where
+        Idx: PartialOrd<U>,
+        U: ?Sized + PartialOrd<Idx>,
+    {
+        <Self as RangeBounds<Idx>>::contains(self, item)
+    }
+}
+
+impl<T: Clone + PartialOrd> RangeBounds<T> for RangeInclusive<T> {
+    fn start_bound(&self) -> Bound<&T> {
+        Included(&self.start)
+    }
+    fn end_bound(&self) -> Bound<&T> {
+        Included(&self.end)
+    }
+}
+
+impl<'a, Idx: Clone + PartialOrd + Step> IntoIterator for &'a RangeInclusive<Idx> {
+    type Item = Idx;
+    type IntoIter = RangeInclusiveIterator<Idx>;
+
+    fn into_iter(self) -> RangeInclusiveIterator<Idx> {
+        self.iter()
+    }
+}
+
+/// An iterator for the `RangeInclusive` type.
+///
+/// By creating a separate iterator, the original range is not mutated.
+pub struct RangeInclusiveIterator<Idx> {
+    /// The current value of the iterator which is returned by `next()`.
+    current: Idx,
+    /// The end value of the iterator.
+    end: Idx
+}
+
+impl<A: Step> Iterator for RangeInclusiveIterator<A> {
+    type Item = A;
+
+    fn next(&mut self) -> Option<Self::Item> {
+        if self.current > self.end {
+            None
+        } else {
+            let n = Step::forward_checked(self.current.clone(), 1).expect("`Step` invariants not upheld");
+            Some(core::mem::replace(&mut self.current, n))
+        }
+    }
+}
+
+impl<A: Step> ExactSizeIterator for RangeInclusiveIterator<A> {
+    fn len(&self) -> usize {
+        Step::steps_between(&self.current, &self.end).map(|x| x+1).unwrap_or(0)
+    }
+}
+
+impl<A: Step> DoubleEndedIterator for RangeInclusiveIterator<A>  {
+    fn next_back(&mut self) -> Option<Self::Item> {
+        if self.current > self.end {
+            None
+        } else {
+            let n = Step::backward_checked(self.end.clone(), 1).expect("`Step` invariants not upheld");
+            Some(core::mem::replace(&mut self.end, n))
+        }
+    }
+}

libs/range_inclusive/src/test.rs

@@ -0,0 +1,117 @@
+extern crate std;
+use self::std::vec::Vec;
+
+use crate::*;
+
+#[test]
+fn greater_end() {
+    let range = RangeInclusive::new(0 , 1);
+    assert!(!range.is_empty());
+    
+    let mut range_elements = Vec::new();
+    for r in range.iter() {
+        range_elements.push(r);
+    }
+    assert_eq!(range_elements[0], range.start);
+    assert_eq!(range_elements[range_elements.len() - 1], range.end);
+    assert_eq!(range_elements.len(), range.end - range.start + 1);
+
+
+    let range = RangeInclusive::new(10 , 17);
+    assert!(!range.is_empty());
+    
+    let mut range_elements = Vec::new();
+    for r in range.iter() {
+        range_elements.push(r);
+    }
+    assert_eq!(range_elements[0], range.start);
+    assert_eq!(range_elements[range_elements.len() - 1], range.end);
+    assert_eq!(range_elements.len(), range.end - range.start + 1);
+
+
+    let range = RangeInclusive::new(597 , 982);
+    assert!(!range.is_empty());
+    
+    let mut range_elements = Vec::new();
+    for r in range.iter() {
+        range_elements.push(r);
+    }
+    assert_eq!(range_elements[0], range.start);
+    assert_eq!(range_elements[range_elements.len() - 1], range.end);
+    assert_eq!(range_elements.len(), range.end - range.start + 1);
+}
+
+#[test]
+fn equal_start_end() {
+    let range = RangeInclusive::new(0 , 0);
+    assert!(!range.is_empty());
+    
+    let mut range_elements = Vec::new();
+    for r in range.iter() {
+        range_elements.push(r);
+    }
+    assert_eq!(range_elements[0], range.start);
+    assert_eq!(range_elements[range_elements.len() - 1], range.end);
+    assert_eq!(range_elements.len(), range.end - range.start + 1);
+    
+    let range = RangeInclusive::new(597 , 597);
+    assert!(!range.is_empty());
+    
+    let mut range_elements = Vec::new();
+    for r in range.iter() {
+        range_elements.push(r);
+    }
+    assert_eq!(range_elements[0], range.start);
+    assert_eq!(range_elements[range_elements.len() - 1], range.end);
+    assert_eq!(range_elements.len(), range.end - range.start + 1);
+}
+
+#[test]
+fn greater_start() {
+    let range = RangeInclusive::new(782 , 597);
+    assert!(range.is_empty());
+    let mut range_elements = Vec::new();
+    for r in range.iter() {
+        range_elements.push(r);
+    }
+    assert!(range_elements.is_empty());
+    
+    let range = RangeInclusive::new(1 , 0);
+    assert!(range.is_empty());
+    let mut range_elements = Vec::new();
+    for r in range.iter() {
+        range_elements.push(r);
+    }
+    assert!(range_elements.is_empty());
+}
+
+#[test]
+fn other_iterators() {
+    let range = RangeInclusive::new(1 , 6);
+    let mut iter = range.iter();
+    assert_eq!(iter.len(), 6);
+    assert_eq!(Some(1), iter.next());
+    
+    assert_eq!(iter.len(), 5);
+    assert_eq!(Some(6), iter.next_back());
+    
+    assert_eq!(iter.len(), 4);
+    assert_eq!(Some(5), iter.next_back());
+    
+    assert_eq!(iter.len(), 3);
+    assert_eq!(Some(2), iter.next());
+    
+    assert_eq!(iter.len(), 2);
+    assert_eq!(Some(3), iter.next());
+    
+    assert_eq!(iter.len(), 1);
+    assert_eq!(Some(4), iter.next());
+    
+    assert_eq!(iter.len(), 0);
+    assert_eq!(None, iter.next());
+    
+    assert_eq!(iter.len(), 0);
+    assert_eq!(None, iter.next_back());
+    
+    assert_eq!(iter.len(), 0);
+}