From c3db5bd1a022ea6f67bdec9d866682f1f5cbaa3f Mon Sep 17 00:00:00 2001 From: ripytide Date: Mon, 5 Dec 2022 01:23:03 +0000 Subject: [PATCH] add more doc examples for overwrite --- README.md | 5 ++ src/range_bounds_map.rs | 112 ++++++++++++++++++++++++++++++++++------ todo.txt | 17 ++++++ 3 files changed, 119 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index dbbce02..361dbca 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,11 @@ there exists no value between them. For example, `2..4` and `4..6` are touching but `2..4` and `6..8` are not, neither are `2..6` and `4..8`. +### Coalesce + +When a `RangeBounds` "coalesces" other `RangeBounds` it absorbs them +to become larger. + ## Example using [`Range`]s ```rust diff --git a/src/range_bounds_map.rs b/src/range_bounds_map.rs index f79cf79..51bc545 100644 --- a/src/range_bounds_map.rs +++ b/src/range_bounds_map.rs @@ -522,7 +522,7 @@ where /// /// # Examples /// ``` - /// use range_bounds_map::{CutError, RangeBoundsMap}; + /// use range_bounds_map::{RangeBoundsMap, TryFromBoundsError}; /// /// let mut base = RangeBoundsMap::try_from([ /// (1..4, false), @@ -537,7 +537,7 @@ where /// /// assert_eq!(base.cut(&(2..40)), Ok(())); /// assert_eq!(base, after_cut); - /// assert_eq!(base.cut(&(60..=80)), Err(CutError)); + /// assert_eq!(base.cut(&(60..=80)), Err(TryFromBoundsError)); /// ``` pub fn cut(&mut self, range_bounds: &Q) -> Result<(), TryFromBoundsError> where @@ -715,6 +715,9 @@ where /// Adds a new (`RangeBounds`, `Value`) pair to the map and /// coalesces into other `RangeBounds` in the map which touch it. /// + /// The `Value` of the coalesced `RangeBounds` is set to the given + /// `Value`. + /// /// If the new `RangeBounds` overlaps one or more `RangeBounds` /// already in the map rather than just touching then an /// [`OverlapError`] is returned and the map is not updated. @@ -726,12 +729,33 @@ where /// # Examples /// ``` /// use range_bounds_map::{ - /// OverlapOrTryFromBoundsError, RangeBoundsMap, + /// OverlapError, OverlapOrTryFromBoundsError, RangeBoundsMap, /// }; /// - /// let mut range_bounds_map = RangeBoundsMap::new(); - /// - /// todo!() + /// let mut range_bounds_map = + /// RangeBoundsMap::try_from([(1..4, false)]).unwrap(); + /// + /// // Touching + /// assert_eq!( + /// range_bounds_map.insert_coalesce_touching(4..6, true), + /// Ok(()) + /// ); + /// + /// // Overlapping + /// assert_eq!( + /// range_bounds_map.insert_coalesce_touching(4..8, false), + /// Err(OverlapOrTryFromBoundsError::Overlap(OverlapError)), + /// ); + /// + /// // Neither Touching or Overlapping + /// assert_eq!( + /// range_bounds_map.insert_coalesce_touching(10..16, false), + /// Ok(()) + /// ); + /// + /// assert_eq!(range_bounds_map.next(), Some((&(1..6), &true))); + /// assert_eq!(range_bounds_map.next(), Some((&(10..16), &false))); + /// assert_eq!(range_bounds_map.next(), None); /// ``` pub fn insert_coalesce_touching( &mut self, @@ -745,16 +769,42 @@ where /// coalesces into other `RangeBounds` in the map which overlap /// it. /// + /// The `Value` of the coalesced `RangeBounds` is set to the given + /// `Value`. + /// /// If the coalesced `RangeBounds` cannot be created with the /// [`TryFromBounds`] trait then a [`TryFromBoundsError`] will be /// returned. /// /// # Examples /// ``` - /// use range_bounds_map::{RangeBoundsMap, TryFromBoundsError}; + /// use range_bounds_map::RangeBoundsMap; /// - /// let mut range_bounds_map = RangeBoundsMap::new(); - /// todo!() + /// let mut range_bounds_map = + /// RangeBoundsMap::try_from([(1..4, false)]).unwrap(); + /// + /// // Touching + /// assert_eq!( + /// range_bounds_map.insert_coalesce_touching(-4..1, true), + /// Ok(()) + /// ); + /// + /// // Overlapping + /// assert_eq!( + /// range_bounds_map.insert_coalesce_touching(2..8, true), + /// Ok(()) + /// ); + /// + /// // Neither Touching or Overlapping + /// assert_eq!( + /// range_bounds_map.insert_coalesce_touching(10..16, false), + /// Ok(()) + /// ); + /// + /// assert_eq!(range_bounds_map.next(), Some((&(-4..1), &true))); + /// assert_eq!(range_bounds_map.next(), Some((&(1..8), &true))); + /// assert_eq!(range_bounds_map.next(), Some((&(10..16), &false))); + /// assert_eq!(range_bounds_map.next(), None); /// ``` pub fn insert_coalesce_overlapping( &mut self, @@ -768,16 +818,41 @@ where /// coalesces into other `RangeBounds` in the map which touch or /// overlap it. /// + /// The `Value` of the coalesced `RangeBounds` is set to the given + /// `Value`. + /// /// If the coalesced `RangeBounds` cannot be created with the /// [`TryFromBounds`] trait then a [`TryFromBoundsError`] will be /// returned. /// /// # Examples /// ``` - /// use range_bounds_map::{RangeBoundsMap, TryFromBoundsError}; + /// use range_bounds_map::RangeBoundsMap; /// - /// let mut range_bounds_map = RangeBoundsMap::new(); - /// todo!() + /// let mut range_bounds_map = + /// RangeBoundsMap::try_from([(1..4, false)]).unwrap(); + /// + /// // Touching + /// assert_eq!( + /// range_bounds_map.insert_coalesce_touching(-4..1, true), + /// Ok(()) + /// ); + /// + /// // Overlapping + /// assert_eq!( + /// range_bounds_map.insert_coalesce_touching(2..8, true), + /// Ok(()) + /// ); + /// + /// // Neither Touching or Overlapping + /// assert_eq!( + /// range_bounds_map.insert_coalesce_touching(10..16, false), + /// Ok(()) + /// ); + /// + /// assert_eq!(range_bounds_map.next(), Some((&(-4..8), &true))); + /// assert_eq!(range_bounds_map.next(), Some((&(10..16), &false))); + /// assert_eq!(range_bounds_map.next(), None); /// ``` pub fn insert_coalesce_touching_or_overlapping( &mut self, @@ -800,10 +875,17 @@ where /// /// # Examples /// ``` - /// use range_bounds_map::{RangeBoundsMap, TryFromBoundsError}; + /// use range_bounds_map::RangeBoundsMap; /// - /// let mut range_bounds_map = RangeBoundsMap::new(); - /// todo!() + /// let mut range_bounds_map = + /// RangeBoundsMap::try_from([(2..8, false)]).unwrap(); + /// + /// assert_eq!(range_bounds_map.overwrite(4..6, true), Ok(())); + /// + /// assert_eq!(range_bounds_map.next(), Some((&(2..4), &false))); + /// assert_eq!(range_bounds_map.next(), Some((&(4..6), &true))); + /// assert_eq!(range_bounds_map.next(), Some((&(6..8), &false))); + /// assert_eq!(range_bounds_map.next(), None); /// ``` pub fn overwrite( &mut self, diff --git a/todo.txt b/todo.txt index c23e3d9..6df7997 100644 --- a/todo.txt +++ b/todo.txt @@ -11,6 +11,23 @@ - add issues to github for all the caveats - review caveats again +- remove all unwraps from examples + +- refactor tests with a bunch of next()s into using collect for + assert_eq + +- copy map to set again + +- add a copy-paste notes to functions returning a TryFromBoundsError + to foward them to: +- add a centralized section showing examples for TryFromBoundsErrors + for the functions that can give them, possibly on the + TryFromBoundsError page in the docs. + +- write something somewhere about wrapper types for RangeBoundsMap + that can simplify function signatures due to known invariants. For + example a wrapper for using K=std::ops::Range which simplifies a LOT + - take a look around idiomatic rust for a bit first - review method parameter names for all public functions