From a4061ffb9286c1e3d7345b4cecd0d93a59ccebcc Mon Sep 17 00:00:00 2001 From: ripytide Date: Fri, 31 Mar 2023 17:06:25 +0100 Subject: [PATCH 1/5] uniformity in docs language --- src/range_bounds_map.rs | 12 ++++++------ src/range_bounds_set.rs | 12 ++++++------ 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/src/range_bounds_map.rs b/src/range_bounds_map.rs index 47b7ccb..e2de9fe 100644 --- a/src/range_bounds_map.rs +++ b/src/range_bounds_map.rs @@ -333,7 +333,7 @@ where /// Adds a new (`RangeBounds`, `Value`) pair to the map without /// modifying other entries. /// - /// If the new `RangeBounds` overlaps one or more `RangeBounds` + /// If the given `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. /// @@ -401,7 +401,7 @@ where } /// Returns an iterator over every (`RangeBounds`, `Value`) pair - /// in the map which overlap the given `range_bounds` in + /// in the map which overlap the given `RangeBounds` in /// ascending order. /// /// # Examples @@ -614,7 +614,7 @@ where } /// Removes every (`RangeBounds`, `Value`) pair in the map which - /// overlaps the given `range_bounds` and returns them in + /// overlaps the given `RangeBounds` and returns them in /// an iterator. /// /// # Examples @@ -1025,7 +1025,7 @@ where /// If successful then a reference to the newly inserted /// `RangeBounds` is returned. /// - /// If the new `RangeBounds` overlaps one or more `RangeBounds` + /// If the given `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. /// `RangeBounds` is returned. @@ -1333,7 +1333,7 @@ where /// If the remaining `RangeBounds` left after the cut are not able /// to be created with the [`TryFromBounds`] trait then a /// [`TryFromBoundsError`] will be returned. - /// + /// /// # Examples /// ``` /// use range_bounds_map::RangeBoundsMap; @@ -1531,7 +1531,7 @@ where /// Similar to [`RangeBoundsMap::overlapping()`] except the /// `(Bound, Bound)`s returned in the iterator have been - /// trimmed/cut by the given `range_bounds`. + /// trimmed/cut by the given `RangeBounds`. /// /// This is sort of the analogue to the AND function between a /// `RangeBounds` AND a [`RangeBoundsMap`]. diff --git a/src/range_bounds_set.rs b/src/range_bounds_set.rs index f57d309..f549571 100644 --- a/src/range_bounds_set.rs +++ b/src/range_bounds_set.rs @@ -177,7 +177,7 @@ where /// Adds a new `RangeBounds` to the set without modifying other /// `RangeBounds` in the set. /// - /// If the new `RangeBounds` overlaps one or more `RangeBounds` + /// If the given `RangeBounds` overlaps one or more `RangeBounds` /// already in the set rather than just touching, then an /// [`OverlapError`] is returned and the set is not updated. /// @@ -228,7 +228,7 @@ where } /// Returns an iterator over every `RangeBounds` in the set which - /// overlap the given `range_bounds` in ascending order. + /// overlap the given `RangeBounds` in ascending order. /// /// # Examples /// ``` @@ -316,7 +316,7 @@ where } /// Removes every `RangeBounds` in the set which overlaps the - /// given `range_bounds` and returns them in an iterator. + /// given `RangeBounds` and returns them in an iterator. /// /// # Examples /// ``` @@ -534,7 +534,7 @@ where /// If successful then a reference to the newly inserted /// `RangeBounds` is returned. /// - /// If the new `RangeBounds` overlaps one or more `RangeBounds` + /// If the given `RangeBounds` overlaps one or more `RangeBounds` /// already in the set rather than just touching, then an /// [`OverlapError`] is returned and the set is not updated. /// @@ -689,7 +689,7 @@ where } /// Adds a new `RangeBounds` to the set and overwrites any other - /// `RangeBounds` that overlap the new `RangeBounds`. + /// `RangeBounds` that overlap the given `RangeBounds`. /// /// This is equivalent to using [`RangeBoundsSet::cut()`] /// followed by [`RangeBoundsSet::insert_strict()`]. @@ -837,7 +837,7 @@ where /// Similar to [`RangeBoundsSet::overlapping()`] except the /// `(Bound, Bound)`s returned in the iterator have been - /// trimmed/cut by the given `range_bounds`. + /// trimmed/cut by the given `RangeBounds`. /// /// This is sort of the analogue to the AND function between a /// `RangeBounds` AND a [`RangeBoundsSet`]. From e2b308a38a2753ccac080bc2ea855b343b4d882f Mon Sep 17 00:00:00 2001 From: ripytide Date: Fri, 31 Mar 2023 17:37:26 +0100 Subject: [PATCH 2/5] added invalid RangeBounds section to readme and made the panics copy-pasta --- README.md | 31 +++++++++++++++++++++++++++++++ src/lib.rs | 2 ++ src/range_bounds_map.rs | 13 ++++++++++--- todo.md | 2 -- 4 files changed, 43 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 63568c9..17478f7 100644 --- a/README.md +++ b/README.md @@ -93,6 +93,32 @@ assert_eq!( ## Key Definitions: +### 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 +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`. + +Here are a few examples of `RangeBounds` and whether they are valid: + +| `RangeBounds` | Valid | +| -------------- | ----- | +| 0..0 | NO | +| 0..1 | YES | +| 9..8 | NO | +| (0.4)..=(-0.2) | NO | +| ..-3 | YES | +| 0.0003.. | YES | +| .. | YES | +| 400..=400 | YES | + ### Overlap Two `RangeBounds` are "overlapping" if there exists a point that is @@ -110,6 +136,11 @@ there exists no value between them. For example, `2..4` and When a `RangeBounds` "merges" other `RangeBounds` it absorbs them to become larger. +### Further Reading + +See Wikipedia's article on Intervals: + + # Improvements/Caveats - Missing some functions common to BTreeMap and BTreeSet like: diff --git a/src/lib.rs b/src/lib.rs index d3e9189..ff332b2 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -101,6 +101,8 @@ along with range_bounds_map. If not, see . //! //! ## Key Definitions: //! +//! ### Invalid RangeBounds +//! //! ### Overlap //! //! Two `RangeBounds` are "overlapping" if there exists a point that is diff --git a/src/range_bounds_map.rs b/src/range_bounds_map.rs index e2de9fe..80053f8 100644 --- a/src/range_bounds_map.rs +++ b/src/range_bounds_map.rs @@ -337,6 +337,11 @@ where /// already in the map rather than just touching, then an /// [`OverlapError`] is returned and the map is not updated. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid RangeBounds`] for more details. + /// /// # Examples /// ``` /// use range_bounds_map::{OverlapError, RangeBoundsMap}; @@ -349,6 +354,8 @@ where /// Err(OverlapError) /// ); /// assert_eq!(range_bounds_map.len(), 1); + /// + /// [`Invalid RangeBounds`]: https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds /// ``` #[tested] pub fn insert_strict( @@ -364,7 +371,7 @@ where let end = BoundOrd::end(range_bounds.end_bound()); if start > end { - panic!("Invalid search range bounds!"); + panic!("Invalid range_bounds!"); } self.starts.insert( @@ -431,7 +438,7 @@ where Q: RangeBounds, { if !is_valid_range_bounds(range_bounds) { - panic!("Invalid range bounds!"); + panic!("Invalid range_bounds!"); } let start = BoundOrd::start(range_bounds.start_bound().cloned()); @@ -1333,7 +1340,7 @@ where /// If the remaining `RangeBounds` left after the cut are not able /// to be created with the [`TryFromBounds`] trait then a /// [`TryFromBoundsError`] will be returned. - /// + /// /// # Examples /// ``` /// use range_bounds_map::RangeBoundsMap; diff --git a/todo.md b/todo.md index 8274376..04ac732 100644 --- a/todo.md +++ b/todo.md @@ -20,8 +20,6 @@ - replace `RangeBounds` with `K` where applicatble in docs - replace rust types URL links with direct rust links -- add a # Panics section to every method that can panic, probably most - given invalid RangeBounds # features From 275adf90075a8dc9cc4266646966b0f0209fafcf Mon Sep 17 00:00:00 2001 From: ripytide Date: Fri, 31 Mar 2023 17:39:31 +0100 Subject: [PATCH 3/5] no need for len() == 0 in an is_empty() wrapper --- src/range_bounds_map.rs | 12 ++++++------ src/range_bounds_set.rs | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/src/range_bounds_map.rs b/src/range_bounds_map.rs index 80053f8..a927f5f 100644 --- a/src/range_bounds_map.rs +++ b/src/range_bounds_map.rs @@ -327,7 +327,7 @@ where /// ``` #[trivial] pub fn is_empty(&self) -> bool { - self.len() == 0 + self.starts.is_empty() } /// Adds a new (`RangeBounds`, `Value`) pair to the map without @@ -337,10 +337,12 @@ where /// already in the map rather than just touching, then an /// [`OverlapError`] is returned and the map is not updated. /// - /// # Panics + /// # Panics /// - /// Panics if the given `range_bounds` is an invalid - /// `RangeBounds`. See [`Invalid RangeBounds`] for more details. + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. /// /// # Examples /// ``` @@ -354,8 +356,6 @@ where /// Err(OverlapError) /// ); /// assert_eq!(range_bounds_map.len(), 1); - /// - /// [`Invalid RangeBounds`]: https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds /// ``` #[tested] pub fn insert_strict( diff --git a/src/range_bounds_set.rs b/src/range_bounds_set.rs index f549571..7121bfb 100644 --- a/src/range_bounds_set.rs +++ b/src/range_bounds_set.rs @@ -171,7 +171,7 @@ where /// ``` #[trivial] pub fn is_empty(&self) -> bool { - self.len() == 0 + self.map.is_empty() } /// Adds a new `RangeBounds` to the set without modifying other From 1be4d476e0dea1f93967d5245b5e25a3493f3aa2 Mon Sep 17 00:00:00 2001 From: ripytide Date: Fri, 31 Mar 2023 17:50:48 +0100 Subject: [PATCH 4/5] add panic sections to all applicable methods' documentation --- src/range_bounds_map.rs | 113 ++++++++++++++++++++++++++++++++++++---- src/range_bounds_set.rs | 105 +++++++++++++++++++++++++++++++++++++ 2 files changed, 209 insertions(+), 9 deletions(-) diff --git a/src/range_bounds_map.rs b/src/range_bounds_map.rs index a927f5f..922b098 100644 --- a/src/range_bounds_map.rs +++ b/src/range_bounds_map.rs @@ -337,12 +337,12 @@ where /// already in the map rather than just touching, then an /// [`OverlapError`] is returned and the map is not updated. /// - /// # Panics + /// # Panics /// - /// Panics if the given `range_bounds` is an invalid - /// `RangeBounds`. See [`Invalid - /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) - /// for more details. + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. /// /// # Examples /// ``` @@ -367,10 +367,7 @@ where return Err(OverlapError); } - let start = BoundOrd::start(range_bounds.start_bound()); - let end = BoundOrd::end(range_bounds.end_bound()); - - if start > end { + if !is_valid_range_bounds(&range_bounds) { panic!("Invalid range_bounds!"); } @@ -385,6 +382,13 @@ where /// Returns `true` if the given `RangeBounds` overlaps any of the /// `RangeBounds` in the map, and `false` if not. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use range_bounds_map::RangeBoundsMap; @@ -411,6 +415,13 @@ where /// in the map which overlap the given `RangeBounds` in /// ascending order. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use range_bounds_map::RangeBoundsMap; @@ -624,6 +635,13 @@ where /// overlaps the given `RangeBounds` and returns them in /// an iterator. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use range_bounds_map::RangeBoundsMap; @@ -688,6 +706,13 @@ where /// partially cut a `RangeBounds` then `V` must be cloned to be /// returned in the iterator. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use std::ops::Bound; @@ -810,6 +835,13 @@ where /// iterator of `(Result, /// Value)`. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use range_bounds_map::{RangeBoundsMap, TryFromBoundsError}; @@ -861,6 +893,13 @@ where /// `RangeBounds` such as `&(..)` or `&(Bound::Unbounded, /// Bound::Unbounded)`. /// + /// # Panics + /// + /// Panics if the given `outer_range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use std::ops::Bound; @@ -955,6 +994,13 @@ where /// Identical to [`RangeBoundsMap::gaps()`] except it returns an /// iterator of `Result`. /// + /// # Panics + /// + /// Panics if the given `outer_range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use std::ops::Bound; @@ -993,6 +1039,13 @@ where /// Returns `true` if the map covers every point in the given /// `RangeBounds`, and `false` if it doesn't. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use range_bounds_map::RangeBoundsMap; @@ -1041,6 +1094,13 @@ where /// [`TryFromBounds`] trait then a [`TryFromBoundsError`] will be /// returned. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use range_bounds_map::{ @@ -1166,6 +1226,13 @@ where /// [`TryFromBounds`] trait then a [`TryFromBoundsError`] will be /// returned. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use range_bounds_map::RangeBoundsMap; @@ -1264,6 +1331,13 @@ where /// [`TryFromBounds`] trait then a [`TryFromBoundsError`] will be /// returned. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use range_bounds_map::RangeBoundsMap; @@ -1341,6 +1415,13 @@ where /// to be created with the [`TryFromBounds`] trait then a /// [`TryFromBoundsError`] will be returned. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use range_bounds_map::RangeBoundsMap; @@ -1543,6 +1624,13 @@ where /// This is sort of the analogue to the AND function between a /// `RangeBounds` AND a [`RangeBoundsMap`]. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use std::ops::Bound; @@ -1600,6 +1688,13 @@ where /// it returns an iterator of `(Result, Value)`. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use range_bounds_map::{RangeBoundsMap, TryFromBoundsError}; diff --git a/src/range_bounds_set.rs b/src/range_bounds_set.rs index 7121bfb..3c59edd 100644 --- a/src/range_bounds_set.rs +++ b/src/range_bounds_set.rs @@ -181,6 +181,13 @@ where /// already in the set rather than just touching, then an /// [`OverlapError`] is returned and the set is not updated. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use range_bounds_map::{OverlapError, RangeBoundsSet}; @@ -205,6 +212,13 @@ where /// Returns `true` if the given `RangeBounds` overlaps any of the /// `RangeBounds` in the set, and `false` if not. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use range_bounds_map::RangeBoundsSet; @@ -230,6 +244,13 @@ where /// Returns an iterator over every `RangeBounds` in the set which /// overlap the given `RangeBounds` in ascending order. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use range_bounds_map::RangeBoundsSet; @@ -318,6 +339,13 @@ where /// Removes every `RangeBounds` in the set which overlaps the /// given `RangeBounds` and returns them in an iterator. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use range_bounds_map::RangeBoundsSet; @@ -355,6 +383,13 @@ where /// are not able be created with the [`TryFromBounds`] trait then /// a [`TryFromBoundsError`] will be returned. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use std::ops::Bound; @@ -396,6 +431,13 @@ where /// Identical to [`RangeBoundsSet::cut()`] except it returns an /// iterator of `Result` /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use range_bounds_map::{RangeBoundsSet, TryFromBoundsError}; @@ -438,6 +480,13 @@ where /// `RangeBounds` such as `&(..)` or `&(Bound::Unbounded, /// Bound::Unbounded)`. /// + /// # Panics + /// + /// Panics if the given `outer_range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use std::ops::Bound; @@ -472,6 +521,13 @@ where /// Identical to [`RangeBoundsSet::gaps()`] except it returns an /// iterator of `Result`. /// + /// # Panics + /// + /// Panics if the given `outer_range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use std::ops::Bound; @@ -503,6 +559,13 @@ where /// Returns `true` if the set covers every point in the given /// `RangeBounds`, and `false` if it doesn't. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use range_bounds_map::RangeBoundsSet; @@ -542,6 +605,13 @@ where /// [`TryFromBounds`] trait then a [`TryFromBoundsError`] will be /// returned. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use range_bounds_map::{ @@ -595,6 +665,13 @@ where /// [`TryFromBounds`] trait then a [`TryFromBoundsError`] will be /// returned. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use range_bounds_map::RangeBoundsSet; @@ -646,6 +723,13 @@ where /// [`TryFromBounds`] trait then a [`TryFromBoundsError`] will be /// returned. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use range_bounds_map::RangeBoundsSet; @@ -698,6 +782,13 @@ where /// to be created with the [`TryFromBounds`] trait then a /// [`TryFromBoundsError`] will be returned. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use range_bounds_map::RangeBoundsSet; @@ -842,6 +933,13 @@ where /// This is sort of the analogue to the AND function between a /// `RangeBounds` AND a [`RangeBoundsSet`]. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use std::ops::Bound; @@ -878,6 +976,13 @@ where /// it returns an iterator of `Result`. /// + /// # Panics + /// + /// Panics if the given `range_bounds` is an invalid + /// `RangeBounds`. See [`Invalid + /// RangeBounds`](https://docs.rs/range_bounds_map/latest/range_bounds_map/index.html#Invalid-RangeBounds) + /// for more details. + /// /// # Examples /// ``` /// use range_bounds_map::{RangeBoundsSet, TryFromBoundsError}; From 33c3c56b3177d3a62ff57ee51f844e4ffb853f0f Mon Sep 17 00:00:00 2001 From: ripytide Date: Fri, 31 Mar 2023 17:56:04 +0100 Subject: [PATCH 5/5] cloned the readme to the lib.rs --- README.md | 2 +- src/lib.rs | 30 ++++++++++++++++++++++++++++++ 2 files changed, 31 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 17478f7..6808e64 100644 --- a/README.md +++ b/README.md @@ -114,7 +114,7 @@ Here are a few examples of `RangeBounds` and whether they are valid: | 0..1 | YES | | 9..8 | NO | | (0.4)..=(-0.2) | NO | -| ..-3 | YES | +| ..(-3) | YES | | 0.0003.. | YES | | .. | YES | | 400..=400 | YES | diff --git a/src/lib.rs b/src/lib.rs index ff332b2..61a1e14 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -103,6 +103,30 @@ along with range_bounds_map. If not, see . //! //! ### 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 +//! 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`. +//! +//! Here are a few examples of `RangeBounds` and whether they are valid: +//! +//! | `RangeBounds` | Valid | +//! | -------------- | ----- | +//! | 0..0 | NO | +//! | 0..1 | YES | +//! | 9..8 | NO | +//! | (0.4)..=(-0.2) | NO | +//! | ..(-3) | YES | +//! | 0.0003.. | YES | +//! | .. | YES | +//! | 400..=400 | YES | +//! //! ### Overlap //! //! Two `RangeBounds` are "overlapping" if there exists a point that is @@ -120,6 +144,11 @@ along with range_bounds_map. If not, see . //! When a `RangeBounds` "merges" other `RangeBounds` it absorbs them //! to become larger. //! +//! ### Further Reading +//! +//! See Wikipedia's article on Intervals: +//! +//! //! # Improvements/Caveats //! //! - Missing some functions common to BTreeMap and BTreeSet like: @@ -155,6 +184,7 @@ along with range_bounds_map. If not, see . //! - //! Very similar to this crate but can only use [`Range`]s and //! [`RangeInclusive`]s as keys in it's `map` and `set` structs (separately). +//! - //! - //! Cool library for fully-generic ranges (unlike std::ops ranges), along //! with a `Ranges` datastructure for storing them (Vec-based