From e2b308a38a2753ccac080bc2ea855b343b4d882f Mon Sep 17 00:00:00 2001
From: ripytide <james.forsterer@gmail.com>
Date: Fri, 31 Mar 2023 17:37:26 +0100
Subject: [PATCH] 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:
+<https://en.wikipedia.org/wiki/Interval_(mathematics)>
+
 # 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 <https://www.gnu.org/licenses/>.
 //!
 //! ## 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<I>,
 	{
 		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