Make all discrete coordinate implements the unmap && improve documents

Author: 38

src/chart/builder.rs

@@ -7,7 +7,8 @@ use crate::style::{IntoTextStyle, SizeDesc, TextStyle};
 use plotters_backend::DrawingBackend;
 
 /// The enum used to specify the position of label area.
-/// This is used when we configure the label area size with the API `set_label_area_size`
+/// This is used when we configure the label area size with the API
+/// [ChartBuilder::set_label_area_size](struct ChartBuilder.html#method.set_label_area_size)
 #[derive(Copy, Clone)]
 pub enum LabelAreaPosition {
     Top = 0,

src/coord/discrete.rs

@@ -1,4 +1,4 @@
-use super::{AsRangedCoord, Ranged, ValueFormatter};
+use super::{AsRangedCoord, Ranged, ReversibleRanged, ValueFormatter};
 use std::ops::Range;
 
 /// The trait indicates the coordinate is discrete
@@ -205,6 +205,14 @@ impl<T> From<T> for SegmentValue<T> {
     }
 }
 
+impl<DC: DiscreteRanged> ReversibleRanged for DC {
+    fn unmap(&self, input: i32, limit: (i32, i32)) -> Option<Self::ValueType> {
+        let idx = (f64::from(input - limit.0) * (self.size() as f64) / f64::from(limit.1 - limit.0))
+            .floor() as usize;
+        self.from_index(idx)
+    }
+}
+
 /// The iterator that can be used to iterate all the values defined by a discrete coordinate
 pub struct DiscreteValueIter<'a, T: DiscreteRanged>(&'a T, usize, usize);
 

src/coord/group_by.rs

@@ -6,7 +6,7 @@ use std::ops::Range;
 /// This is useful, for example, when we have an X axis is a integer and denotes days.
 /// And we are expecting the tick mark denotes weeks, in this way we can make the range
 /// spec grouping by 7 elements.
-/// With the help of the GroupBy decorator, this can be archived quite easily: 
+/// With the help of the GroupBy decorator, this can be archived quite easily:
 ///```rust
 ///use plotters::prelude::*;
 ///let mut buf = vec![0;1024*768*3];

src/coord/linspace.rs

@@ -153,13 +153,19 @@ where
 /// to a discrete coordinate by a giving step.
 ///
 /// For example, range `0f32..100f32` is a continuous coordinate, thus this prevent us having a
-/// histogram on it. In this case, to get a histogram, we need to split the original range to a
+/// histogram on it since Plotters doesn't know how to segment the range into buckets.
+/// In this case, to get a histogram, we need to split the original range to a
 /// set of discrete buckets (for example, 0.5 per bucket).
 ///
 /// The linspace decorate abstracting this method. For example, we can have a discrete coordinate:
 /// `(0f32..100f32).step(0.5)`.
 ///
-/// Linspace also supports different types of bucket matching method: ceil, floor, round or exact.
+/// Linspace also supports different types of bucket matching method - This configuration alters the behavior of
+/// [DiscreteCoord::index_of](../trait.DiscreteCoord.html#tymethod.index_of) for Linspace coord spec
+/// - **Flooring**, the value falls into the nearst bucket smaller than it. See [Linspace::use_floor](struct.Linspace.html#method.use_floor)
+/// - **Round**,   the value falls into the nearst bucket. See [Linearspace::use_round](struct.Linspace.html#method.use_round)
+/// - **Ceiling**, the value falls into the nearst bucket larger than itself. See [Linspace::use_ceil](struct.Linspace.html#method.use_ceil)
+/// - **Exact Matchting**, the value must be exactly same as the butcket value.  See [Linspace::use_exact](struct.Linspace.html#method.use_exact)
 #[derive(Clone)]
 pub struct Linspace<T: Ranged, S: Clone, R: LinspaceRoundingMethod<T::ValueType>>
 where

src/coord/logarithmic.rs

@@ -2,7 +2,8 @@ use super::{AsRangedCoord, Ranged, RangedCoordf64};
 use std::marker::PhantomData;
 use std::ops::Range;
 
-/// The trait for the type that is able to be presented in the log scale
+/// The trait for the type that is able to be presented in the log scale.
+/// This trait is primarily used by [LogRange](struct.LogRange.html).
 pub trait LogScalable: Clone {
     /// Make the conversion from the type to the floating point number
     fn as_f64(&self) -> f64;
@@ -47,7 +48,8 @@ impl_log_scalable!(i, u64);
 impl_log_scalable!(f, f32);
 impl_log_scalable!(f, f64);
 
-/// The decorator type for a range of a log-scaled value
+/// The logarithmic coodinate decorator.
+/// This decorator is used to make the axis rendered as logarithmically.
 pub struct LogRange<V: LogScalable>(pub Range<V>);
 
 impl<V: LogScalable + Clone> Clone for LogRange<V> {

src/coord/mod.rs

@@ -18,7 +18,6 @@ for a interactive figure.
 `RangedCoord` is the 2D cartesian coordinate system that has two `Ranged` axis.
 A ranged axis can be logarithmic and by applying an logarithmic axis, the figure is logarithmic scale.
 Also, the ranged axis can be deserted, and this is required by the histogram series.
-
 */
 use plotters_backend::BackendCoord;
 
@@ -37,7 +36,9 @@ mod slice;
 pub use slice::RangedSlice;
 
 #[cfg(feature = "chrono")]
-pub use datetime::{IntoMonthly, IntoYearly, RangedDate, RangedDateTime, RangedDuration};
+pub use datetime::{
+    IntoMonthly, IntoYearly, Monthly, RangedDate, RangedDateTime, RangedDuration, Yearly,
+};
 pub use numeric::{
     RangedCoordf32, RangedCoordf64, RangedCoordi128, RangedCoordi32, RangedCoordi64,
     RangedCoordu128, RangedCoordu32, RangedCoordu64,

src/coord/numeric.rs

@@ -40,7 +40,21 @@ macro_rules! impl_ranged_type_trait {
         }
     };
 }
+macro_rules! impl_reverse_mapping_trait {
+    ($type:ty, $name: ident) => {
+        impl ReversibleRanged for $name {
+            fn unmap(&self, p: i32, (min, max): (i32, i32)) -> Option<$type> {
+                if p < min.min(max) || p > max.max(min) || min == max {
+                    return None;
+                }
 
+                let logical_offset = f64::from(p - min) / f64::from(max - min);
+
+                return Some(((self.1 - self.0) as f64 * logical_offset + self.0 as f64) as $type);
+            }
+        }
+    };
+}
 macro_rules! make_numeric_coord {
     ($type:ty, $name:ident, $key_points:ident, $doc: expr) => {
         #[doc = $doc]
@@ -78,18 +92,6 @@ macro_rules! make_numeric_coord {
                 return self.0..self.1;
             }
         }
-
-        impl ReversibleRanged for $name {
-            fn unmap(&self, p:i32, (min,max): (i32, i32)) -> Option<$type> {
-                if p < min.min(max) || p > max.max(min) {
-                    return None;
-                }
-
-                let logical_offset = (p - min) as f64 / (max - min) as f64;
-
-                return Some(((self.1 - self.0) as f64 * logical_offset + self.0 as f64) as $type);
-            }
-        }
     };
 }
 
@@ -204,12 +206,14 @@ make_numeric_coord!(
     compute_f32_key_points,
     "The ranged coordinate for type f32"
 );
+impl_reverse_mapping_trait!(f32, RangedCoordf32);
 make_numeric_coord!(
     f64,
     RangedCoordf64,
     compute_f64_key_points,
     "The ranged coordinate for type f64"
 );
+impl_reverse_mapping_trait!(f64, RangedCoordf64);
 make_numeric_coord!(
     u32,
     RangedCoordu32,