refactored and reworded all the docs. most importantly changed from RangeBounds to the more readable range word
This commit is contained in:
ripytide
parent
d4dad4bae0
commit
2b8995d3d8
@ -4,8 +4,8 @@ version = "0.1.1"
|
||||
authors = ["James Forster <james.forsterer@gmail.com>"]
|
||||
edition = "2021"
|
||||
description = """
|
||||
This crate provides `RangeBoundsMap` and `RangeBoundsSet`
|
||||
Data Structures for storing intervals. Based off BTreeMap.
|
||||
This crate provides [`RangeBoundsMap`] and [`RangeBoundsSet`], Data
|
||||
Structures for storing non-overlapping intervals based of [`BTreeMap`].
|
||||
"""
|
||||
documentation = "https://docs.rs/range_bounds_map"
|
||||
readme = "README.md"
|
||||
|
||||
75
README.md
75
README.md
@ -9,13 +9,8 @@
|
||||
<img src="logo.svg" alt="range_bounds_map_logo" width="350">
|
||||
</p>
|
||||
|
||||
This crate provides [`RangeBoundsMap`] and [`RangeBoundsSet`].
|
||||
|
||||
[`RangeBoundsMap`] is an ordered map of non-overlapping [`RangeBounds`]
|
||||
based on [`BTreeMap`].
|
||||
|
||||
[`RangeBoundsSet`] is an ordered set of non-overlapping [`RangeBounds`]
|
||||
based on [`RangeBoundsMap`].
|
||||
This crate provides [`RangeBoundsMap`] and [`RangeBoundsSet`], Data
|
||||
Structures for storing non-overlapping intervals based of [`BTreeMap`].
|
||||
|
||||
## Example using [`Range`]s
|
||||
|
||||
@ -95,21 +90,22 @@ assert_eq!(
|
||||
|
||||
### Invalid RangeBounds
|
||||
|
||||
Within this crate, not all `RangeBounds` are considered valid
|
||||
`RangeBounds`. The definition of the validity of a `RangeBounds` used
|
||||
within this crate is that a `RangeBounds` is only valid if it contains
|
||||
Within this crate, not all ranges are considered valid
|
||||
ranges. The definition of the validity of a range used
|
||||
within this crate is that a range is only valid if it contains
|
||||
at least one value of the underlying domain.
|
||||
|
||||
For example, `4..6` is considered valid as it contains the values `4`
|
||||
and `5`, however, `4..4` is considered invalid as it contains no
|
||||
values. Another example of invalid `RangeBounds` are those with
|
||||
`start_bound()`s with greater values than their `end_bound()`s, such
|
||||
as `5..2` or `100..=40`.
|
||||
For example, `4..6` is considered valid as it contains the values
|
||||
`4` and `5`, however, `4..4` is considered invalid as it contains
|
||||
no values. Another example of invalid range are those whose start
|
||||
values are greater than their end values. such as `5..2` or
|
||||
`100..=40`.
|
||||
|
||||
Here are a few examples of `RangeBounds` and whether they are valid:
|
||||
Here are a few examples of ranges and whether they are valid:
|
||||
|
||||
| `RangeBounds` | Valid |
|
||||
| range | valid |
|
||||
| -------------- | ----- |
|
||||
| 0..=0 | YES |
|
||||
| 0..0 | NO |
|
||||
| 0..1 | YES |
|
||||
| 9..8 | NO |
|
||||
@ -121,35 +117,29 @@ Here are a few examples of `RangeBounds` and whether they are valid:
|
||||
|
||||
### Overlap
|
||||
|
||||
Two `RangeBounds` are "overlapping" if there exists a point that is
|
||||
contained within both `RangeBounds`.
|
||||
Two ranges are "overlapping" if there exists a point that is contained
|
||||
within both ranges.
|
||||
|
||||
### Touching
|
||||
|
||||
Two `RangeBounds` are "touching" if they do not overlap and
|
||||
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`.
|
||||
Two ranges are "touching" if they do not overlap and 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`.
|
||||
|
||||
### Merging
|
||||
|
||||
When a `RangeBounds` "merges" other `RangeBounds` it absorbs them
|
||||
to become larger.
|
||||
When a range "merges" other ranges it absorbs them to become larger.
|
||||
|
||||
### Further Reading
|
||||
|
||||
See Wikipedia's article on Intervals:
|
||||
See Wikipedia's article on mathematical Intervals:
|
||||
<https://en.wikipedia.org/wiki/Interval_(mathematics)>
|
||||
|
||||
# Improvements/Caveats
|
||||
|
||||
- Missing some functions common to BTreeMap and BTreeSet like:
|
||||
- `clear()`
|
||||
- `is_subset()`
|
||||
- etc... prob a bunch more
|
||||
- Not particularly optimized, (which doesn't mean it's neccessarily slow)
|
||||
- Can't use TryFrom<(Bound, Bound)> instead of [`TryFromBounds`] (relys on
|
||||
upstream to impl, see [this thread](https://internals.rust-lang.org/t/range-should-impl-tryfrom-bound-bound))
|
||||
- I had to create a new trait: [`TryFromBounds`] rather than using
|
||||
`TryFrom<(Bound, Bound)>` (relys on upstream to impl, see [this
|
||||
thread](https://internals.rust-lang.org/t/range-should-impl-tryfrom-bound-bound))
|
||||
|
||||
# Credit
|
||||
|
||||
@ -158,15 +148,19 @@ however, I later stumbled across [`rangemap`] which also used a
|
||||
`StartBound`: [`Ord`] bodge. [`rangemap`] then became my main source
|
||||
of inspiration.
|
||||
|
||||
The aim for my library was to become a more generic
|
||||
superset of [`rangemap`], following from [this
|
||||
Later I then undid the [`Ord`] bodge and switched to my own full-code
|
||||
port of [`BTreeMap`], inspired and forked from [`copse`], for it's
|
||||
increased flexibility.
|
||||
|
||||
# Origin
|
||||
|
||||
The aim for this library was to become a more generic superset of
|
||||
[`rangemap`], following from [this
|
||||
issue](https://github.com/jeffparsons/rangemap/issues/56) and [this
|
||||
pull request](https://github.com/jeffparsons/rangemap/pull/57) in
|
||||
which I changed [`rangemap`]'s [`RangeMap`] to use [`RangeBounds`]s as
|
||||
keys before I realized it might be easier and simpler to just write it
|
||||
all from scratch. Which ended up working really well with some
|
||||
simplifications (BoundOrd) I made which made some of the code much
|
||||
easier to work with.
|
||||
all from scratch.
|
||||
|
||||
# Similar Crates
|
||||
|
||||
@ -209,5 +203,6 @@ topic area:
|
||||
[`rangeinclusivemap`]: https://docs.rs/rangemap/latest/rangemap/inclusive_map/struct.RangeInclusiveMap.html#
|
||||
[`rangeinclusive`]: https://doc.rust-lang.org/std/ops/struct.RangeInclusive.html
|
||||
[`ord`]: https://doc.rust-lang.org/std/cmp/trait.Ord.html
|
||||
[`RangeBoundsMap`]: https://docs.rs/range_bounds_map/latest/range_bounds_map/range_bounds_map/struct.RangeBoundsMap.html
|
||||
[`RangeBoundsSet`]: https://docs.rs/range_bounds_map/latest/range_bounds_map/range_bounds_set/struct.RangeBoundsSet.html
|
||||
[`rangeboundsmap`]: https://docs.rs/range_bounds_map/latest/range_bounds_map/range_bounds_map/struct.RangeBoundsMap.html
|
||||
[`rangeboundsset`]: https://docs.rs/range_bounds_map/latest/range_bounds_map/range_bounds_set/struct.RangeBoundsSet.html
|
||||
[`copse`]: https://github.com/eggyal/copse
|
||||
|
||||
77
src/lib.rs
77
src/lib.rs
@ -17,13 +17,8 @@ You should have received a copy of the GNU Affero General Public License
|
||||
along with range_bounds_map. If not, see <https://www.gnu.org/licenses/>.
|
||||
*/
|
||||
|
||||
//! This crate provides [`RangeBoundsMap`] and [`RangeBoundsSet`].
|
||||
//!
|
||||
//! [`RangeBoundsMap`] is an ordered map of non-overlapping [`RangeBounds`]
|
||||
//! based on [`BTreeMap`].
|
||||
//!
|
||||
//! [`RangeBoundsSet`] is an ordered set of non-overlapping [`RangeBounds`]
|
||||
//! based on [`RangeBoundsMap`].
|
||||
//! This crate provides [`RangeBoundsMap`] and [`RangeBoundsSet`], Data
|
||||
//! Structures for storing non-overlapping intervals based of [`BTreeMap`].
|
||||
//!
|
||||
//! ## Example using [`Range`]s
|
||||
//!
|
||||
@ -105,21 +100,22 @@ along with range_bounds_map. If not, see <https://www.gnu.org/licenses/>.
|
||||
//!
|
||||
//! ### Invalid RangeBounds
|
||||
//!
|
||||
//! Within this crate, not all `RangeBounds` are considered valid
|
||||
//! `RangeBounds`. The definition of the validity of a `RangeBounds` used
|
||||
//! within this crate is that a `RangeBounds` is only valid if it contains
|
||||
//! Within this crate, not all ranges are considered valid
|
||||
//! ranges. The definition of the validity of a range used
|
||||
//! within this crate is that a range is only valid if it contains
|
||||
//! at least one value of the underlying domain.
|
||||
//!
|
||||
//! For example, `4..6` is considered valid as it contains the values `4`
|
||||
//! and `5`, however, `4..4` is considered invalid as it contains no
|
||||
//! values. Another example of invalid `RangeBounds` are those with
|
||||
//! `start_bound()`s with greater values than their `end_bound()`s, such
|
||||
//! as `5..2` or `100..=40`.
|
||||
//! For example, `4..6` is considered valid as it contains the values
|
||||
//! `4` and `5`, however, `4..4` is considered invalid as it contains
|
||||
//! no values. Another example of invalid range are those whose start
|
||||
//! values are greater than their end values. such as `5..2` or
|
||||
//! `100..=40`.
|
||||
//!
|
||||
//! Here are a few examples of `RangeBounds` and whether they are valid:
|
||||
//! Here are a few examples of ranges and whether they are valid:
|
||||
//!
|
||||
//! | `RangeBounds` | Valid |
|
||||
//! | range | valid |
|
||||
//! | -------------- | ----- |
|
||||
//! | 0..=0 | YES |
|
||||
//! | 0..0 | NO |
|
||||
//! | 0..1 | YES |
|
||||
//! | 9..8 | NO |
|
||||
@ -131,35 +127,29 @@ along with range_bounds_map. If not, see <https://www.gnu.org/licenses/>.
|
||||
//!
|
||||
//! ### Overlap
|
||||
//!
|
||||
//! Two `RangeBounds` are "overlapping" if there exists a point that is
|
||||
//! contained within both `RangeBounds`.
|
||||
//! Two ranges are "overlapping" if there exists a point that is contained
|
||||
//! within both ranges.
|
||||
//!
|
||||
//! ### Touching
|
||||
//!
|
||||
//! Two `RangeBounds` are "touching" if they do not overlap and
|
||||
//! 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`.
|
||||
//! Two ranges are "touching" if they do not overlap and 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`.
|
||||
//!
|
||||
//! ### Merging
|
||||
//!
|
||||
//! When a `RangeBounds` "merges" other `RangeBounds` it absorbs them
|
||||
//! to become larger.
|
||||
//! When a range "merges" other ranges it absorbs them to become larger.
|
||||
//!
|
||||
//! ### Further Reading
|
||||
//!
|
||||
//! See Wikipedia's article on Intervals:
|
||||
//! See Wikipedia's article on mathematical Intervals:
|
||||
//! <https://en.wikipedia.org/wiki/Interval_(mathematics)>
|
||||
//!
|
||||
//! # Improvements/Caveats
|
||||
//!
|
||||
//! - Missing some functions common to BTreeMap and BTreeSet like:
|
||||
//! - `clear()`
|
||||
//! - `is_subset()`
|
||||
//! - etc... prob a bunch more
|
||||
//! - Not particularly optimized, (which doesn't mean it's neccessarily slow)
|
||||
//! - Can't use TryFrom<(Bound, Bound)> instead of [`TryFromBounds`] (relys on
|
||||
//! upstream to impl, see [this thread](https://internals.rust-lang.org/t/range-should-impl-tryfrom-bound-bound))
|
||||
//! - I had to create a new trait: [`TryFromBounds`] rather than using
|
||||
//! `TryFrom<(Bound, Bound)>` (relys on upstream to impl, see [this
|
||||
//! thread](https://internals.rust-lang.org/t/range-should-impl-tryfrom-bound-bound))
|
||||
//!
|
||||
//! # Credit
|
||||
//!
|
||||
@ -168,15 +158,19 @@ along with range_bounds_map. If not, see <https://www.gnu.org/licenses/>.
|
||||
//! `StartBound`: [`Ord`] bodge. [`rangemap`] then became my main source
|
||||
//! of inspiration.
|
||||
//!
|
||||
//! The aim for my library was to become a more generic
|
||||
//! superset of [`rangemap`], following from [this
|
||||
//! Later I then undid the [`Ord`] bodge and switched to my own full-code
|
||||
//! port of [`BTreeMap`], inspired and forked from [`copse`], for it's
|
||||
//! increased flexibility.
|
||||
//!
|
||||
//! # Origin
|
||||
//!
|
||||
//! The aim for this library was to become a more generic superset of
|
||||
//! [`rangemap`], following from [this
|
||||
//! issue](https://github.com/jeffparsons/rangemap/issues/56) and [this
|
||||
//! pull request](https://github.com/jeffparsons/rangemap/pull/57) in
|
||||
//! which I changed [`rangemap`]'s [`RangeMap`] to use [`RangeBounds`]s as
|
||||
//! keys before I realized it might be easier and simpler to just write it
|
||||
//! all from scratch. Which ended up working really well with some
|
||||
//! simplifications (BoundOrd) I made which made some of the code much
|
||||
//! easier to work with.
|
||||
//! all from scratch.
|
||||
//!
|
||||
//! # Similar Crates
|
||||
//!
|
||||
@ -219,8 +213,9 @@ along with range_bounds_map. If not, see <https://www.gnu.org/licenses/>.
|
||||
//! [`rangeinclusivemap`]: https://docs.rs/rangemap/latest/rangemap/inclusive_map/struct.RangeInclusiveMap.html#
|
||||
//! [`rangeinclusive`]: https://doc.rust-lang.org/std/ops/struct.RangeInclusive.html
|
||||
//! [`ord`]: https://doc.rust-lang.org/std/cmp/trait.Ord.html
|
||||
//! [`RangeBoundsMap`]: https://docs.rs/range_bounds_map/latest/range_bounds_map/range_bounds_map/struct.RangeBoundsMap.html
|
||||
//! [`RangeBoundsSet`]: https://docs.rs/range_bounds_map/latest/range_bounds_map/range_bounds_set/struct.RangeBoundsSet.html
|
||||
//! [`rangeboundsmap`]: https://docs.rs/range_bounds_map/latest/range_bounds_map/range_bounds_map/struct.RangeBoundsMap.html
|
||||
//! [`rangeboundsset`]: https://docs.rs/range_bounds_map/latest/range_bounds_map/range_bounds_set/struct.RangeBoundsSet.html
|
||||
//! [`copse`]: https://github.com/eggyal/copse
|
||||
|
||||
#![feature(is_some_and)]
|
||||
#![feature(let_chains)]
|
||||
@ -229,8 +224,8 @@ along with range_bounds_map. If not, see <https://www.gnu.org/licenses/>.
|
||||
#![allow(clippy::needless_return)]
|
||||
|
||||
pub(crate) mod bound_ord;
|
||||
pub(crate) mod utils;
|
||||
pub mod test_ranges;
|
||||
pub(crate) mod utils;
|
||||
|
||||
pub mod range_bounds_map;
|
||||
pub mod range_bounds_set;
|
||||
|
||||
@ -50,6 +50,8 @@ use crate::TryFromBounds;
|
||||
/// `V` is the generic type parameter for the values associated with the
|
||||
/// keys in the map.
|
||||
///
|
||||
/// Phrasing it another way: `I` is the point type, `K` is the range type, and `V` is the value type.
|
||||
///
|
||||
/// # Examples
|
||||
/// ```
|
||||
/// use range_bounds_map::test_ranges::ie;
|
||||
@ -303,7 +305,7 @@ where
|
||||
}
|
||||
}
|
||||
|
||||
/// Returns the number of `RangeBounds` in the map.
|
||||
/// Returns the number of ranges in the map.
|
||||
///
|
||||
/// # Examples
|
||||
/// ```
|
||||
@ -320,7 +322,7 @@ where
|
||||
self.inner.len()
|
||||
}
|
||||
|
||||
/// Returns `true` if the map contains no `RangeBounds`, and
|
||||
/// Returns `true` if the map contains no ranges, and
|
||||
/// `false` if it does.
|
||||
///
|
||||
/// # Examples
|
||||
@ -338,8 +340,8 @@ where
|
||||
self.inner.is_empty()
|
||||
}
|
||||
|
||||
/// Returns `true` if the given `RangeBounds` overlaps any of the
|
||||
/// `RangeBounds` in the map, and `false` if not.
|
||||
/// Returns `true` if the given range overlaps any of the
|
||||
/// other ranges in the map, and `false` if not.
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
@ -372,9 +374,8 @@ where
|
||||
self.overlapping(range).next().is_some()
|
||||
}
|
||||
|
||||
/// Returns an iterator over every (`RangeBounds`, `Value`) entry
|
||||
/// in the map which overlap the given `RangeBounds` in
|
||||
/// ascending order.
|
||||
/// Returns an iterator over every entry in the map that overlaps
|
||||
/// the given range in ascending order.
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
@ -421,9 +422,8 @@ where
|
||||
.range(start_comp, start_bound, end_comp, end_bound)
|
||||
}
|
||||
|
||||
/// Returns a reference to the `Value` corresponding to the
|
||||
/// `RangeBounds` in the map that overlaps the given point, if
|
||||
/// any.
|
||||
/// Returns a reference to the value corresponding to the range in
|
||||
/// the map that overlaps the given point, if any.
|
||||
///
|
||||
/// # Examples
|
||||
/// ```
|
||||
@ -445,8 +445,30 @@ where
|
||||
self.get_entry_at_point(point).map(|(_, value)| value)
|
||||
}
|
||||
|
||||
/// Returns `true` if the map contains a `RangeBounds` that
|
||||
/// overlaps the given point, and `false` if not.
|
||||
/// Returns a mutable reference to the value corresponding to the
|
||||
/// range that overlaps the given point, if any.
|
||||
///
|
||||
/// # Examples
|
||||
/// ```
|
||||
/// use range_bounds_map::test_ranges::ie;
|
||||
/// use range_bounds_map::RangeBoundsMap;
|
||||
/// let mut map =
|
||||
/// RangeBoundsMap::from_slice_strict([(ie(1, 4), false)])
|
||||
/// .unwrap();
|
||||
///
|
||||
/// if let Some(x) = map.get_at_point_mut(2) {
|
||||
/// *x = true;
|
||||
/// }
|
||||
///
|
||||
/// assert_eq!(map.get_at_point(1), Some(&true));
|
||||
/// ```
|
||||
pub fn get_at_point_mut(&mut self, point: I) -> Option<&mut V> {
|
||||
self.inner
|
||||
.get_mut(overlapping_start_comp(Bound::Included(point)))
|
||||
}
|
||||
|
||||
/// Returns `true` if the map contains a range that overlaps the
|
||||
/// given point, and `false` if not.
|
||||
///
|
||||
/// # Examples
|
||||
/// ```
|
||||
@ -468,30 +490,8 @@ where
|
||||
self.get_entry_at_point(point).is_some()
|
||||
}
|
||||
|
||||
/// Returns a mutable reference to the `Value` corresponding to
|
||||
/// the `RangeBounds` that overlaps the given point, if any.
|
||||
///
|
||||
/// # Examples
|
||||
/// ```
|
||||
/// use range_bounds_map::test_ranges::ie;
|
||||
/// use range_bounds_map::RangeBoundsMap;
|
||||
/// let mut map =
|
||||
/// RangeBoundsMap::from_slice_strict([(ie(1, 4), false)])
|
||||
/// .unwrap();
|
||||
///
|
||||
/// if let Some(x) = map.get_at_point_mut(2) {
|
||||
/// *x = true;
|
||||
/// }
|
||||
///
|
||||
/// assert_eq!(map.get_at_point(1), Some(&true));
|
||||
/// ```
|
||||
pub fn get_at_point_mut(&mut self, point: I) -> Option<&mut V> {
|
||||
self.inner
|
||||
.get_mut(overlapping_start_comp(Bound::Included(point)))
|
||||
}
|
||||
|
||||
/// Returns an (`RangeBounds`, `Value`) entry corresponding to the
|
||||
/// `RangeBounds` that overlaps the given point, if any.
|
||||
/// Returns the entry corresponding to the range that
|
||||
/// overlaps the given point, if any.
|
||||
///
|
||||
/// # Examples
|
||||
/// ```
|
||||
@ -514,8 +514,8 @@ where
|
||||
.get_key_value(overlapping_start_comp(Bound::Included(point)))
|
||||
}
|
||||
|
||||
/// Returns an iterator over every (`RangeBounds`, `Value`) entry
|
||||
/// in the map in ascending order.
|
||||
/// Returns an iterator over every entry in the map in ascending
|
||||
/// order.
|
||||
///
|
||||
/// # Examples
|
||||
/// ```
|
||||
@ -540,9 +540,8 @@ where
|
||||
self.inner.iter()
|
||||
}
|
||||
|
||||
/// Removes every (`RangeBounds`, `Value`) entry in the map which
|
||||
/// overlaps the given `RangeBounds` and returns them in
|
||||
/// an iterator.
|
||||
/// Removes every entry in the map which overlaps the given range
|
||||
/// and returns them in an iterator.
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
@ -591,20 +590,18 @@ where
|
||||
.drain_filter(move |inner_range, _| overlaps(*inner_range, range));
|
||||
}
|
||||
|
||||
/// Cuts a given `RangeBounds` out of the map and returns an
|
||||
/// iterator of the full or partial `RangeBounds` that were cut in
|
||||
/// as `((Bound, Bound), Value)`.
|
||||
/// Cuts a given range out of the map and returns an iterator of
|
||||
/// the full or partial ranges that were cut.
|
||||
///
|
||||
/// If the remaining `RangeBounds` left in the map after the cut
|
||||
/// are not able be created with the [`TryFromBounds`] trait then
|
||||
/// a [`TryFromBoundsError`] will be returned and the map will not
|
||||
/// be cut.
|
||||
/// If the remaining ranges left in the map after the cut would
|
||||
/// not be able be created with the [`TryFromBounds`] trait then a
|
||||
/// [`TryFromBoundsError`] will be returned and the map will not
|
||||
/// be cut at all.
|
||||
///
|
||||
/// `V` must implement `Clone` as if you try to cut out the center
|
||||
/// of a `RangeBounds` in the map it will split into two different
|
||||
/// (`RangeBounds`, `Value`) entries using `Clone`. Or if you
|
||||
/// partially cut a `RangeBounds` then `V` must be cloned to be
|
||||
/// returned in the iterator.
|
||||
/// of a range in the map it will split into two different entries
|
||||
/// using `Clone`. Or if you partially cut a range then
|
||||
/// `V` must be cloned to be returned in the iterator.
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
@ -795,9 +792,8 @@ where
|
||||
.chain(keeping_after_entry.into_iter()));
|
||||
}
|
||||
|
||||
/// Returns an iterator of `(Bound<&I>, Bound<&I>)` over all the
|
||||
/// maximally-sized gaps in the map that are also within the given
|
||||
/// `outer_range`.
|
||||
/// Returns an iterator of ranges over all the maximally-sized
|
||||
/// gaps in the map that are also within the given `outer_range`.
|
||||
///
|
||||
/// To get all possible gaps call `gaps()` with an unbounded
|
||||
/// `RangeBounds` such as `&(..)` or `&(Bound::Unbounded,
|
||||
@ -890,7 +886,7 @@ where
|
||||
}
|
||||
|
||||
/// Returns `true` if the map covers every point in the given
|
||||
/// `RangeBounds`, and `false` if it doesn't.
|
||||
/// range, and `false` if it does not.
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
@ -925,12 +921,11 @@ where
|
||||
self.gaps(range).next().is_none()
|
||||
}
|
||||
|
||||
/// Adds a new (`RangeBounds`, `Value`) entry to the map without
|
||||
/// modifying other entries.
|
||||
/// Adds a new entry to the map without modifying other entries.
|
||||
///
|
||||
/// If the given `RangeBounds` overlaps one or more `RangeBounds`
|
||||
/// already in the map, then an [`OverlapError`] is returned and
|
||||
/// the map is not updated.
|
||||
/// If the given range overlaps one or more ranges already in the
|
||||
/// map, then an [`OverlapError`] is returned and the map is not
|
||||
/// updated.
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
@ -1013,20 +1008,21 @@ where
|
||||
Ok(returning)
|
||||
}
|
||||
|
||||
/// Adds a new (`RangeBounds`, `Value`) entry to the map and
|
||||
/// merges into other `RangeBounds` in the map which touch it.
|
||||
/// Adds a new entry to the map and merges into other ranges in
|
||||
/// the map which touch it.
|
||||
///
|
||||
/// The `Value` of the merged `RangeBounds` is set to the given
|
||||
/// `Value`.
|
||||
/// The value of the merged-together range is set to the value given for
|
||||
/// this insertion.
|
||||
///
|
||||
/// If successful then a reference to the newly inserted
|
||||
/// `RangeBounds` is returned.
|
||||
/// If successful then the newly inserted (possibly merged) range is
|
||||
/// returned.
|
||||
///
|
||||
/// If the given `RangeBounds` overlaps one or more `RangeBounds`
|
||||
/// already in the map, then an [`OverlapError`] is returned and
|
||||
/// the map is not updated.
|
||||
/// If the given range overlaps one or more ranges already in the
|
||||
/// map, then an [`OverlapError`] is returned and the map is not
|
||||
/// updated.
|
||||
///
|
||||
/// If the merged `RangeBounds` cannot be created with the
|
||||
/// If the range merges with one or two touching ranges and the
|
||||
/// merged-together range cannot be created with the
|
||||
/// [`TryFromBounds`] trait then a [`TryFromBoundsError`] will be
|
||||
/// returned.
|
||||
///
|
||||
@ -1110,20 +1106,19 @@ where
|
||||
.map_err(OverlapOrTryFromBoundsError::TryFromBounds)
|
||||
}
|
||||
|
||||
/// Adds a new (`RangeBounds`, `Value`) entry to the map and
|
||||
/// merges into other `RangeBounds` in the map which overlap
|
||||
/// it.
|
||||
/// Adds a new entry to the map and merges into other ranges in
|
||||
/// the map which overlap it.
|
||||
///
|
||||
/// The `Value` of the merged `RangeBounds` is set to the given
|
||||
/// `Value`.
|
||||
/// The value of the merged-together range is set to the value given for
|
||||
/// this insertion.
|
||||
///
|
||||
/// If successful then a reference to the newly inserted
|
||||
/// `RangeBounds` is returned.
|
||||
///
|
||||
/// If the merged `RangeBounds` cannot be created with the
|
||||
/// [`TryFromBounds`] trait then a [`TryFromBoundsError`] will be
|
||||
/// If successful then the newly inserted (possibly merged) range is
|
||||
/// returned.
|
||||
///
|
||||
/// If the range merges other ranges and the merged-together range
|
||||
/// cannot be created with the [`TryFromBounds`] trait then a
|
||||
/// [`TryFromBoundsError`] will be returned.
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
/// Panics if the given `range` is an invalid
|
||||
@ -1193,20 +1188,19 @@ where
|
||||
)
|
||||
}
|
||||
|
||||
/// Adds a new (`RangeBounds`, `Value`) entry to the map and
|
||||
/// merges into other `RangeBounds` in the map which touch or
|
||||
/// overlap it.
|
||||
/// Adds a new entry to the map and merges into other ranges in
|
||||
/// the map which touch or overlap it.
|
||||
///
|
||||
/// The `Value` of the merged `RangeBounds` is set to the given
|
||||
/// `Value`.
|
||||
/// The value of the merged-together range is set to the value given for
|
||||
/// this insertion.
|
||||
///
|
||||
/// If successful then a reference to the newly inserted
|
||||
/// `RangeBounds` is returned.
|
||||
///
|
||||
/// If the merged `RangeBounds` cannot be created with the
|
||||
/// [`TryFromBounds`] trait then a [`TryFromBoundsError`] will be
|
||||
/// If successful then the newly inserted (possibly merged) range is
|
||||
/// returned.
|
||||
///
|
||||
/// If the range merges other ranges and the merged-together range
|
||||
/// cannot be created with the [`TryFromBounds`] trait then a
|
||||
/// [`TryFromBoundsError`] will be returned.
|
||||
///
|
||||
/// # Panics
|
||||
///
|
||||
/// Panics if the given `range` is an invalid
|
||||
@ -1288,16 +1282,15 @@ where
|
||||
)
|
||||
}
|
||||
|
||||
/// Adds a new (`RangeBounds`, `Value`) entry to the map and
|
||||
/// overwrites any other `RangeBounds` that overlap the new
|
||||
/// `RangeBounds`.
|
||||
/// Adds a new entry to the map and overwrites any other ranges
|
||||
/// that overlap the new range.
|
||||
///
|
||||
/// This is equivalent to using [`RangeBoundsMap::cut()`]
|
||||
/// followed by [`RangeBoundsMap::insert_strict()`]. Hence the
|
||||
/// same `V: Clone` trait bound applies.
|
||||
///
|
||||
/// If the remaining `RangeBounds` left after the cut are not able
|
||||
/// to be created with the [`TryFromBounds`] trait then a
|
||||
/// If the remaining ranges left after the cut are not able to be
|
||||
/// created with the [`TryFromBounds`] trait then a
|
||||
/// [`TryFromBoundsError`] will be returned.
|
||||
///
|
||||
/// # Panics
|
||||
@ -1340,8 +1333,7 @@ where
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
/// Returns the first (`RangeBounds`, `Value`) entry in the map, if
|
||||
/// any.
|
||||
/// Returns the first entry in the map, if any.
|
||||
///
|
||||
/// # Examples
|
||||
/// ```
|
||||
@ -1361,8 +1353,7 @@ where
|
||||
self.inner.first_key_value()
|
||||
}
|
||||
|
||||
/// Returns the last (`RangeBounds`, `Value`) entry in the map, if
|
||||
/// any.
|
||||
/// Returns the last entry in the map, if any.
|
||||
///
|
||||
/// # Examples
|
||||
/// ```
|
||||
@ -1384,8 +1375,8 @@ where
|
||||
self.inner.last_key_value()
|
||||
}
|
||||
|
||||
/// Allocate a `RangeBoundsMap` and move the given (`RangeBounds`,
|
||||
/// `Value`) entries from the slice into the map using
|
||||
/// Allocates a `RangeBoundsMap` and moves the given entries from
|
||||
/// the given slice into the map using
|
||||
/// [`RangeBoundsMap::insert_strict()`].
|
||||
///
|
||||
/// May return an `Err` while inserting. See
|
||||
@ -1650,8 +1641,8 @@ mod tests {
|
||||
|
||||
use super::*;
|
||||
use crate::bound_ord::BoundOrd;
|
||||
use crate::utils::{config, Config, CutResult};
|
||||
use crate::test_ranges::{ee, ei, ie, ii, iu, u, ue, ui, uu, AnyRange};
|
||||
use crate::utils::{config, Config, CutResult};
|
||||
|
||||
//only every other number to allow mathematical_overlapping_definition
|
||||
//to test between bounds in finite using smaller intervalled finite
|
||||
|
||||
@ -20,6 +20,8 @@ use crate::{
|
||||
/// `K` is the generic type parameter for the [`RangeBounds`]
|
||||
/// implementing type in the set.
|
||||
///
|
||||
/// Phrasing it another way: `I` is the point type and `K` is the range type.
|
||||
///
|
||||
/// See [`RangeBoundsMap`] for more details.
|
||||
///
|
||||
/// [`RangeBounds`]: https://doc.rust-lang.org/std/ops/trait.RangeBounds.html
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user