yggdrasil/discrete_range_map
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

add more doc examples for overwrite

Browse Source
This commit is contained in:
ripytide
2022-12-05 01:23:03 +00:00
parent 23e0b49332
commit c3db5bd1a0
3 changed files with 119 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+5
View File
@@ -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
src/range_bounds_map.rs
+97 -15
View File
@@ -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<Q>(&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,
todo.txt
+17
View File
@@ -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