histogram/bin.rs: Multiple Improvements

- Rewrites and reformats docs. Hopefully it's more aligned to the style in std
  library.
- Replaced `left-inclusive-right-exclusive` by `left-closed-right-open`, which
  is more common in maths.

Author: lebensterben

src/histogram/bins.rs

@@ -1,42 +1,51 @@
 use ndarray::prelude::*;
 use std::ops::{Index, Range};
 
-/// `Edges` is a sorted collection of `A` elements used
-/// to represent the boundaries of intervals ([`Bins`]) on
-/// a 1-dimensional axis.
+/// A sorted collection of type `A` elements used to represent the boundaries of intervals, i.e.
+/// [`Bins`] on a 1-dimensional axis.
 ///
-/// [`Bins`]: struct.Bins.html
-/// # Example:
+/// **Note** that all intervals are left-closed and right-open. See examples below.
+///
+/// # Examples
 ///
 /// ```
-/// use ndarray_stats::histogram::{Edges, Bins};
+/// use ndarray_stats::histogram::{Bins, Edges};
 /// use noisy_float::types::n64;
 ///
 /// let unit_edges = Edges::from(vec![n64(0.), n64(1.)]);
 /// let unit_interval = Bins::new(unit_edges);
-/// // left inclusive
+/// // left-closed
 /// assert_eq!(
 ///     unit_interval.range_of(&n64(0.)).unwrap(),
 ///     n64(0.)..n64(1.),
 /// );
-/// // right exclusive
+/// // right-open
 /// assert_eq!(
 ///     unit_interval.range_of(&n64(1.)),
 ///     None
 /// );
 /// ```
+///
+/// [`Bins`]: struct.Bins.html
 #[derive(Clone, Debug, Eq, PartialEq)]
 pub struct Edges<A: Ord> {
     edges: Vec<A>,
 }
 
 impl<A: Ord> From<Vec<A>> for Edges<A> {
-    /// Get an `Edges` instance from a `Vec<A>`:
-    /// the vector will be sorted in increasing order
-    /// using an unstable sorting algorithm and duplicates
-    /// will be removed.
+    /// Converts a `Vec<A>` into an `Edges<A>`, consuming the edges.
+    /// The vector will be sorted in increasing order using an unstable sorting algorithm, with
+    /// duplicates removed.
     ///
-    /// # Example:
+    /// # Current implementation
+    ///
+    /// The current sorting algorithm is the same as [`std::slice::sort_unstable()`][sort],
+    /// which is based on [pattern-defeating quicksort][pdqsort].
+    ///
+    /// This sort is unstable (i.e., may reorder equal elements), in-place (i.e., does not allocate)
+    /// , and O(n log n) worst-case.
+    ///
+    /// # Examples
     ///
     /// ```
     /// use ndarray::array;
@@ -49,6 +58,9 @@ impl<A: Ord> From<Vec<A>> for Edges<A> {
     ///     15
     /// );
     /// ```
+    ///
+    /// [sort]: https://doc.rust-lang.org/stable/std/primitive.slice.html#method.sort_unstable
+    /// [pdqsort]: https://github.com/orlp/pdqsort
     fn from(mut edges: Vec<A>) -> Self {
         // sort the array in-place
         edges.sort_unstable();
@@ -59,11 +71,19 @@ impl<A: Ord> From<Vec<A>> for Edges<A> {
 }
 
 impl<A: Ord + Clone> From<Array1<A>> for Edges<A> {
-    /// Get an `Edges` instance from a `Array1<A>`:
-    /// the array elements will be sorted in increasing order
-    /// using an unstable sorting algorithm and duplicates will be removed.
+    /// Converts an `Array1<A>` into an `Edges<A>`, consuming the 1-dimensional array.
+    /// The array will be sorted in increasing order using an unstable sorting algorithm, with
+    /// duplicates removed.
     ///
-    /// # Example:
+    /// # Current implementation
+    ///
+    /// The current sorting algorithm is the same as [`std::slice::sort_unstable()`][sort],
+    /// which is based on [pattern-defeating quicksort][pdqsort].
+    ///
+    /// This sort is unstable (i.e., may reorder equal elements), in-place (i.e., does not allocate)
+    /// , and O(n log n) worst-case.
+    ///
+    /// # Examples
     ///
     /// ```
     /// use ndarray_stats::histogram::Edges;
@@ -75,6 +95,9 @@ impl<A: Ord + Clone> From<Array1<A>> for Edges<A> {
     ///     10
     /// );
     /// ```
+    ///
+    /// [sort]: https://doc.rust-lang.org/stable/std/primitive.slice.html#method.sort_unstable
+    /// [pdqsort]: https://github.com/orlp/pdqsort
     fn from(edges: Array1<A>) -> Self {
         let edges = edges.to_vec();
         Self::from(edges)
@@ -84,11 +107,13 @@ impl<A: Ord + Clone> From<Array1<A>> for Edges<A> {
 impl<A: Ord> Index<usize> for Edges<A> {
     type Output = A;
 
-    /// Get the `i`-th edge.
+    /// Returns a reference to the `i`-th edge in `self`.
     ///
-    /// **Panics** if the index `i` is out of bounds.
+    /// # Panics
     ///
-    /// # Example:
+    /// Panics if the index `i` is out of bounds.
+    ///
+    /// # Examples
     ///
     /// ```
     /// use ndarray_stats::histogram::Edges;
@@ -105,9 +130,9 @@ impl<A: Ord> Index<usize> for Edges<A> {
 }
 
 impl<A: Ord> Edges<A> {
-    /// Number of edges in `self`.
+    /// Returns the number of edges in `self`.
     ///
-    /// # Example:
+    /// # Examples
     ///
     /// ```
     /// use ndarray_stats::histogram::Edges;
@@ -125,25 +150,25 @@ impl<A: Ord> Edges<A> {
 
     /// Returns `true` if `self` contains no edges.
     ///
-    /// # Example:
+    /// # Examples
     ///
     /// ```
     /// use ndarray_stats::histogram::Edges;
     /// use noisy_float::types::{N64, n64};
     ///
     /// let edges = Edges::<N64>::from(vec![]);
     /// assert_eq!(edges.is_empty(), true);
+    ///
     /// let edges = Edges::from(vec![n64(0.), n64(2.), n64(5.)]);
     /// assert_eq!(edges.is_empty(), false);
     /// ```
     pub fn is_empty(&self) -> bool {
         self.edges.is_empty()
     }
 
-    /// Borrow an immutable reference to the edges as a 1-dimensional
-    /// array view.
+    /// Returns an immutable 1-dimensional array view of edges.
     ///
-    /// # Example:
+    /// # Examples
     ///
     /// ```
     /// use ndarray::array;
@@ -159,21 +184,26 @@ impl<A: Ord> Edges<A> {
         ArrayView1::from(&self.edges)
     }
 
-    /// Given `value`, it returns an option:
-    /// - `Some((left, right))`, where `right=left+1`, if there are two consecutive edges in
-    /// `self` such that `self[left] <= value < self[right]`;
+    /// Returns indices of two consecutive `edges` in `self`, if the interval they represent
+    /// contains the given `value`, or returns `None` otherwise.
+    ///
+    /// That is to say, it returns
+    /// - `Some((left, right))`, where `left` and `right` are the indices of two consecutive edges
+    /// in `self` and `right == left + 1`, if `self[left] <= value < self[right]`;
     /// - `None`, otherwise.
     ///
-    /// # Example:
+    /// # Examples
     ///
     /// ```
     /// use ndarray_stats::histogram::Edges;
     ///
     /// let edges = Edges::from(vec![0, 2, 3]);
+    /// // `1` is in the interval [0, 2), whose indices are (0, 1)
     /// assert_eq!(
     ///     edges.indices_of(&1),
     ///     Some((0, 1))
     /// );
+    /// // `5` is not in any of intervals
     /// assert_eq!(
     ///     edges.indices_of(&5),
     ///     None
@@ -193,17 +223,17 @@ impl<A: Ord> Edges<A> {
         }
     }
 
+    /// Returns an iterator over the `edges` in `self`.
     pub fn iter(&self) -> impl Iterator<Item = &A> {
         self.edges.iter()
     }
 }
 
-/// `Bins` is a sorted collection of non-overlapping
-/// 1-dimensional intervals.
+/// A sorted collection of non-overlapping 1-dimensional intervals.
 ///
-/// All intervals are left-inclusive and right-exclusive.
+/// **Note** that all intervals are left-closed and right-open.
 ///
-/// # Example:
+/// # Examples
 ///
 /// ```
 /// use ndarray_stats::histogram::{Edges, Bins};
@@ -228,16 +258,17 @@ pub struct Bins<A: Ord> {
 }
 
 impl<A: Ord> Bins<A> {
-    /// Given a collection of [`Edges`], it returns the corresponding `Bins` instance.
+    /// Returns a `Bins` instance where each bin corresponds to two consecutive members of the given
+    /// [`Edges`], consuming the edges.
     ///
     /// [`Edges`]: struct.Edges.html
     pub fn new(edges: Edges<A>) -> Self {
         Bins { edges }
     }
 
-    /// Returns the number of bins.
+    /// Returns the number of bins in `self`.
     ///
-    /// # Example:
+    /// # Examples
     ///
     /// ```
     /// use ndarray_stats::histogram::{Edges, Bins};
@@ -257,70 +288,89 @@ impl<A: Ord> Bins<A> {
         }
     }
 
-    /// Returns `true` if the number of bins is zero, or in other words, if the
-    /// number of edges is 0 or 1.
+    /// Returns `true` if the number of bins is zero, i.e. if the number of edges is 0 or 1.
     ///
-    /// # Example:
+    /// # Examples
     ///
     /// ```
     /// use ndarray_stats::histogram::{Edges, Bins};
     /// use noisy_float::types::{N64, n64};
     ///
+    /// // At least 2 edges is needed to represent 1 interval
+    /// let edges = Edges::from(vec![n64(0.), n64(1.), n64(3.)]);
+    /// let bins = Bins::new(edges);
+    /// assert_eq!(bins.is_empty(), false);
+    ///
+    /// // No valid interval == Empty
     /// let edges = Edges::<N64>::from(vec![]);
     /// let bins = Bins::new(edges);
     /// assert_eq!(bins.is_empty(), true);
     /// let edges = Edges::from(vec![n64(0.)]);
     /// let bins = Bins::new(edges);
     /// assert_eq!(bins.is_empty(), true);
-    /// let edges = Edges::from(vec![n64(0.), n64(1.), n64(3.)]);
-    /// let bins = Bins::new(edges);
-    /// assert_eq!(bins.is_empty(), false);
     /// ```
     pub fn is_empty(&self) -> bool {
         self.len() == 0
     }
 
-    /// Given `value`, it returns:
-    /// - `Some(i)`, if the `i`-th bin in `self` contains `value`;
-    /// - `None`, if `value` does not belong to any of the bins in `self`.
+    /// Returns the index of the bin in `self` that contains the given `value`,
+    /// or returns `None` if `value` does not belong to any bins in `self`.
     ///
-    /// # Example:
+    /// # Examples
+    ///
+    /// Basic usage:
     ///
     /// ```
     /// use ndarray_stats::histogram::{Edges, Bins};
     ///
     /// let edges = Edges::from(vec![0, 2, 4, 6]);
     /// let bins = Bins::new(edges);
     /// let value = 1;
+    /// // The first bin [0, 2) contains `1`
     /// assert_eq!(
     ///     bins.index_of(&1),
     ///     Some(0)
     /// );
+    /// // No bin contains 100
+    /// assert_eq!(
+    ///     bins.index_of(&100),
+    ///     None
+    /// )
+    /// ```
+    ///
+    /// Chaining [`Bins::index`] and [`Bins::index_of`] to get the boundaries of the bin containing
+    /// the value:
+    ///
+    /// ```
+    /// # use ndarray_stats::histogram::{Edges, Bins};
+    /// # let edges = Edges::from(vec![0, 2, 4, 6]);
+    /// # let bins = Bins::new(edges);
+    /// # let value = 1;
     /// assert_eq!(
-    ///     bins.index(bins.index_of(&1).unwrap()),
-    ///     0..2
+    ///     // using `Option::map` to avoid panic on index out-of-bounds
+    ///     bins.index_of(&1).map(|i| bins.index(i)),
+    ///     Some(0..2)
     /// );
     /// ```
     pub fn index_of(&self, value: &A) -> Option<usize> {
         self.edges.indices_of(value).map(|t| t.0)
     }
 
-    /// Given `value`, it returns:
-    /// - `Some(left_edge..right_edge)`, if there exists a bin in `self` such that
-    ///  `left_edge <= value < right_edge`;
-    /// - `None`, otherwise.
+    /// Returns a range as the bin which contains the given `value`, or returns `None` otherwise.
     ///
-    /// # Example:
+    /// # Examples
     ///
     /// ```
     /// use ndarray_stats::histogram::{Edges, Bins};
     ///
     /// let edges = Edges::from(vec![0, 2, 4, 6]);
     /// let bins = Bins::new(edges);
+    /// // [0, 2) contains `1`
     /// assert_eq!(
     ///     bins.range_of(&1),
     ///     Some(0..2)
     /// );
+    /// // `10` is not in any interval
     /// assert_eq!(
     ///     bins.range_of(&10),
     ///     None
@@ -337,11 +387,13 @@ impl<A: Ord> Bins<A> {
         })
     }
 
-    /// Get the `i`-th bin.
+    /// Returns a range as the bin at the given `index` position.
+    ///
+    /// # Panics
     ///
-    /// **Panics** if `index` is out of bounds.
+    /// Panics if `index` is out of bounds.
     ///
-    /// # Example:
+    /// # Examples
     ///
     /// ```
     /// use ndarray_stats::histogram::{Edges, Bins};
@@ -401,7 +453,7 @@ mod edges_tests {
     }
 
     #[quickcheck]
-    fn edges_are_right_exclusive(v: Vec<i32>) -> bool {
+    fn edges_are_right_open(v: Vec<i32>) -> bool {
         let edges = Edges::from(v);
         let view = edges.as_array_view();
         if view.len() == 0 {
@@ -413,7 +465,7 @@ mod edges_tests {
     }
 
     #[quickcheck]
-    fn edges_are_left_inclusive(v: Vec<i32>) -> bool {
+    fn edges_are_left_closed(v: Vec<i32>) -> bool {
         let edges = Edges::from(v);
         match edges.len() {
             1 => true,
@@ -445,7 +497,7 @@ mod bins_tests {
 
     #[test]
     #[should_panic]
-    fn get_panics_for_out_of_bound_indexes() {
+    fn get_panics_for_out_of_bounds_indexes() {
         let edges = Edges::from(vec![0]);
         let bins = Bins::new(edges);
         // we need at least two edges to make a valid bin!