Merge pull request #61 from ripytide/gqdit

Version `0.8.0` bringing various addition and improvements.

CHANGELOG.md

@@ -9,6 +9,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## Unreleased - ReleaseDate
 
+### Added
+- Added the `Gqdit` data-structure with all the proper documentation and
+  examples for all its methods
+- Added a new table to the readme/top-level module docs for describing all
+  the different data-structures in the crate for comparison with one
+  another
+- Added another method to `InclusiveInterval`, `contains_interval()`
+
+### Changed
+- Renamed `contains_entire_interval()` methods to `contains_interval()` to match
+  `InclusiveInterval::contains_interval()`
+- Renamed `InclusiveInterval::contains()` to
+  `InclusiveInterval::contains_point()` to match the new
+  `InclusiveInterval::contains_interval()` method
+- `serde`'s Serialize and Deserialize implementations are now optional via a
+  "serde" feature which is documented in the features section of the
+  readme/top-level module docs
+
 ## 0.8.0 - 2024-01-28
 
 ### Added

Cargo.toml

@@ -4,8 +4,8 @@ version = "0.8.0"
 authors = ["James Forster <james.forsterer@gmail.com>"]
 edition = "2021"
 description = """
-This crate provides NoditMap, NoditSet and ZosditMap, Discrete
-Interval Tree data-structures, which are based off BTreeMap.
+This crate provides Discrete Interval Tree Data-Structures, which are based
+off BTreeMap.
 """
 documentation = "https://docs.rs/nodit"
 readme = "README.md"
@@ -16,14 +16,20 @@ keywords = ["data-structures", "map", "data", "library"]
 categories = ["data-structures"]
 
 [dependencies]
-serde = { version = "1.0.193", features = ["derive"], default-features = false }
+serde = { version = "1.0.193", features = [
+	"derive",
+], default-features = false, optional = true }
 btree_monstrousity = { version = "0.0.4", features = [
 	"btree_drain_filter",
 	"btree_cursors",
 ], default-features = false }
 itertools = { version = "0.12.0", default-features = false }
 smallvec = { version = "1.13.1", default-features = false }
 
+[features]
+default = []
+serde = ["dep:serde"]
+
 [dev-dependencies]
 pretty_assertions = "1.4.0"
 

README.md

@@ -9,19 +9,29 @@
 <img src="logo.png" alt="nodit_logo" width="350">
 </p>
 
-This crate provides [`NoditMap`], [`NoditSet`] and [`ZosditMap`], Discrete
-Interval Tree data-structures, which are based off [`BTreeMap`].
+This crate provides Discrete Interval Tree Data-Structures, which are based
+off [`BTreeMap`].
 
 `no_std` is supported and should work with the default features.
 
+Several Discrete Interval Tree data-structures have been implemented, here
+is a brief summary of each of them and why you might use them:
+
+| Struct|Abreviation|Use-Case|
+|-----|------|------|
+|[`NoditMap`]|Non-Overlapping Discrete Interval Tree Map| General purpose way of associating data with intervals that do not overlap|
+|[`NoditSet`]|Non-Overlapping Discrete Interval Tree Set| Useful for when you want to store intervals but don't want/need to associate data with each interval|
+|[`ZosditMap`]|Zero-Overlap Sequential Discrete Interval Tree Map| Useful for time-graph traversal algorithms and possibly other things|
+|[`Gqdit`]|Gap-Query Discrete Interval Tree| Useful for when you have a set of different non-overlapping intervals and want to perform efficient gap-query searches over all the sets of intervals|
+
 ## `Copy` is partially required
 
 Due to implementation complications with non-`Copy` types the
-datastructures currently require both the interval type and the points the
+data-structures currently require both the interval type and the points the
 intervals are over to be `Copy`. However, the value type used when using
-the [`NoditMap`] does not have to be `Copy`. In fact the only
-required traits on the value type are sometimes `Clone` or `Eq` but only
-for some methods so if in doubt check a methods trait bounds.
+the [`NoditMap`] does not have to be `Copy`. In fact the only required
+traits on the value type are sometimes `Clone` or `Eq` but only for some
+methods so if in doubt check a methods trait bounds.
 
 ## Example using an Inclusive-Exclusive interval
 
@@ -139,8 +149,7 @@ from an empty map if the type was an infinite type such as `BigInt`
 since it has no maximum value.
 
 A handy trick you can use to pretend to have infinite types when you
-don't expect to reach to top end of your type is to use [`Actual
-Infinity`] to pretend you have an `Infinity`. For example, if you were
+don't expect to reach to top end of your type is to use [`Actual Infinity`] to pretend you have an `Infinity`. For example, if you were
 using `u8` as your point type then you could create a wrapper type such
 as this:
 
@@ -281,7 +290,10 @@ See Wikipedia's article on mathematical Intervals:
 
 ## Features
 
-This crate currently has no features
+|Feature Name| Description|
+|-----------|-----|
+|`default`|The implicit default feature enabled by default which currently does not activate any other features|
+|`serde`|Enables the optional `serde` dependency and implements `serde::Serialize` and `serde::Deserialize` on all the types in this crate|
 
 ## Credit
 
@@ -310,7 +322,7 @@ topic area, beware my biases when reading:
 - <https://docs.rs/btree-range-map>
 - <https://docs.rs/ranges>
   Cool library for fully-generic ranges (unlike std::ops ranges), along
-  with a `Ranges` datastructure for storing them (Vec-based
+  with a `Ranges` data-structure for storing them (Vec-based
   unfortunately)
 - <https://docs.rs/intervaltree>
   Allows overlapping intervals but is immutable unfortunately
@@ -330,8 +342,8 @@ topic area, beware my biases when reading:
   unsafe.
 - <https://docs.rs/rust-lapper>
   Another sort-of immutable (can insert but its very expensive)
-  interval datastructure optimised for lots of intervals of the same
-  size such as their staple usecase of genomic datasets.
+  interval data-structure optimised for lots of intervals of the same
+  size such as their staple use-case of genomic datasets.
 - <https://docs.rs/store-interval-tree>
   An interval tree very similar to this crate and `rangemap` with many
   of the same methods (and lots of doc examples!) except using a custom
@@ -344,25 +356,26 @@ topic area, beware my biases when reading:
 - <https://docs.rs/bio> and <https://docs.rs/rudac>
   Both essentially identical to `store-interval-tree` as it looks like
   `store-interval-tree` is a fork of `rudac`'s interval tree. `bio` in
-  particular seems targeted at bioinfographics.
+  particular seems targeted at bio-infographics.
 
+[`actual infinity`]: https://en.wikipedia.org/wiki/Actual_infinity
+[`bigint`]: https://docs.rs/num-bigint/latest/num_bigint/struct.BigInt.html
 [`btreemap`]: https://doc.rust-lang.org/std/collections/struct.BTreeMap.html
 [`btree_monstrousity`]: https://github.com/ripytide/btree_monstrousity
-[`range`]: https://doc.rust-lang.org/std/ops/struct.Range.html
-[`rangemap`]: https://docs.rs/rangemap/latest/rangemap/
-[`rangeinclusive`]: https://doc.rust-lang.org/std/ops/struct.RangeInclusive.html
+[`continuous`]: https://en.wikipedia.org/wiki/List_of_continuity-related_mathematical_topics
 [`copse`]: https://github.com/eggyal/copse
+[`discrete_range_map`]: https://docs.rs/discrete_range_map
 [`discrete`]: https://en.wikipedia.org/wiki/Discrete_mathematics
-[`continuous`]: https://en.wikipedia.org/wiki/List_of_continuity-related_mathematical_topics
-[`interval-mathematics`]: https://en.wikipedia.org/wiki/Interval_(mathematics)
-[`actual infinity`]: https://en.wikipedia.org/wiki/Actual_infinity
 [`finite`]: https://en.wiktionary.org/wiki/finite#Adjective
-[`range_bounds_map`]: https://docs.rs/range_bounds_map
-[`discrete_range_map`]: https://docs.rs/discrete_range_map
+[`get_key_value_at_point()`]: https://docs.rs/nodit/latest/nodit/nodit/map/struct.NoditMap.html#method.get_key_value_at_point
+[`gqdit`]: https://docs.rs/nodit/latest/nodit/gqdit/struct.Gqdit.html
+[`interval-mathematics`]: https://en.wikipedia.org/wiki/Interval_(mathematics)
+[`noditmap`]: https://docs.rs/nodit/latest/nodit/nodit/map/struct.NoditMap.html
+[`noditset`]: https://docs.rs/nodit/latest/nodit/nodit/set/struct.NoditSet.html
 [`nodit`]: https://docs.rs/nodit
-[`bigint`]: https://docs.rs/num-bigint/latest/num_bigint/struct.BigInt.html
 [`num_bigint`]: https://docs.rs/num-bigint
-[`get_key_value_at_point()`]: https://docs.rs/nodit/latest/nodit/nodit/map/struct.NoditMap.html#method.get_key_value_at_point
-[`NoditMap`]: https://docs.rs/nodit/latest/nodit/nodit/map/struct.NoditMap.html
-[`NoditSet`]: https://docs.rs/nodit/latest/nodit/nodit/set/struct.NoditSet.html
-[`ZosditMap`]: https://docs.rs/nodit/latest/nodit/zosdit/map/struct.ZosditMap.html
+[`rangeinclusive`]: https://doc.rust-lang.org/std/ops/struct.RangeInclusive.html
+[`rangemap`]: https://docs.rs/rangemap/latest/rangemap/
+[`range_bounds_map`]: https://docs.rs/range_bounds_map
+[`range`]: https://doc.rust-lang.org/std/ops/struct.Range.html
+[`zosditmap`]: https://docs.rs/nodit/latest/nodit/zosdit/map/struct.ZosditMap.html