Prevent other crates from implementing our traits (#38)

* Prevent other crates from implementing our traits

This allows us to freely add new functionality to the traits without
breaking changes.

* Make PrivateMarker a param instead of return type

This still prevents other crates from implementing our traits, but it
has the advantage that it also prevents them from calling the
`__private__` methods.

* Improve docs of __private__ method

Author: jturner314

src/correlation.rs

@@ -119,6 +119,8 @@ where
     fn pearson_correlation(&self) -> Array2<A>
     where
         A: Float + FromPrimitive;
+
+    private_decl! {}
 }
 
 impl<A: 'static, S> CorrelationExt<A, S> for ArrayBase<S, Ix2>
@@ -164,6 +166,8 @@ where
         // element-wise division
         cov / std_matrix
     }
+
+    private_impl! {}
 }
 
 #[cfg(test)]

src/entropy.rs

@@ -120,6 +120,8 @@ where
     where
         S2: Data<Elem = A>,
         A: Float;
+
+    private_decl! {}
 }
 
 impl<A, S, D> EntropyExt<A, S, D> for ArrayBase<S, D>
@@ -212,6 +214,8 @@ where
         let cross_entropy = -temp.sum();
         Ok(cross_entropy)
     }
+
+    private_impl! {}
 }
 
 #[cfg(test)]

src/histogram/histograms.rs

@@ -147,6 +147,8 @@ where
     fn histogram(&self, grid: Grid<A>) -> Histogram<A>
     where
         A: Ord;
+
+    private_decl! {}
 }
 
 impl<A, S> HistogramExt<A, S> for ArrayBase<S, Ix2>
@@ -161,4 +163,6 @@ where
         }
         histogram
     }
+
+    private_impl! {}
 }

src/lib.rs

@@ -48,6 +48,39 @@ pub use quantile::{interpolate, Quantile1dExt, QuantileExt};
 pub use sort::Sort1dExt;
 pub use summary_statistics::SummaryStatisticsExt;
 
+#[macro_use]
+mod private {
+    /// This is a public type in a private module, so it can be included in
+    /// public APIs, but other crates can't access it.
+    pub struct PrivateMarker;
+
+    /// Defines an associated function for a trait that is impossible for other
+    /// crates to implement. This makes it possible to add new associated
+    /// types/functions/consts/etc. to the trait without breaking changes.
+    macro_rules! private_decl {
+        () => {
+            /// This method makes this trait impossible to implement outside of
+            /// `ndarray-stats` so that we can freely add new methods, etc., to
+            /// this trait without breaking changes.
+            ///
+            /// We don't anticipate any other crates needing to implement this
+            /// trait, but if you do have such a use-case, please let us know.
+            ///
+            /// **Warning** This method is not considered part of the public
+            /// API, and client code should not rely on it being present. It
+            /// may be removed in a non-breaking release.
+            fn __private__(&self, _: crate::private::PrivateMarker);
+        };
+    }
+
+    /// Implements the associated function defined by `private_decl!`.
+    macro_rules! private_impl {
+        () => {
+            fn __private__(&self, _: crate::private::PrivateMarker) {}
+        };
+    }
+}
+
 mod correlation;
 mod entropy;
 pub mod errors;

src/maybe_nan/mod.rs

@@ -289,6 +289,8 @@ where
         S: DataMut,
         D: RemoveAxis,
         F: FnMut(ArrayViewMut1<'a, A::NotNan>) -> B;
+
+    private_decl! {}
 }
 
 impl<A, S, D> MaybeNanExt<A, S, D> for ArrayBase<S, D>
@@ -365,6 +367,8 @@ where
     {
         self.map_axis_mut(axis, |lane| mapping(A::remove_nan_mut(lane)))
     }
+
+    private_impl! {}
 }
 
 #[cfg(test)]

src/quantile/interpolate.rs

@@ -44,6 +44,8 @@ pub trait Interpolate<T> {
     /// or if `None` is provided for the higher value when it's needed.
     #[doc(hidden)]
     fn interpolate(lower: Option<T>, higher: Option<T>, q: N64, len: usize) -> T;
+
+    private_decl! {}
 }
 
 /// Select the higher value.
@@ -69,6 +71,7 @@ impl<T> Interpolate<T> for Higher {
     fn interpolate(_lower: Option<T>, higher: Option<T>, _q: N64, _len: usize) -> T {
         higher.unwrap()
     }
+    private_impl! {}
 }
 
 impl<T> Interpolate<T> for Lower {
@@ -81,6 +84,7 @@ impl<T> Interpolate<T> for Lower {
     fn interpolate(lower: Option<T>, _higher: Option<T>, _q: N64, _len: usize) -> T {
         lower.unwrap()
     }
+    private_impl! {}
 }
 
 impl<T> Interpolate<T> for Nearest {
@@ -97,6 +101,7 @@ impl<T> Interpolate<T> for Nearest {
             higher.unwrap()
         }
     }
+    private_impl! {}
 }
 
 impl<T> Interpolate<T> for Midpoint
@@ -115,6 +120,7 @@ where
         let higher = higher.unwrap();
         lower.clone() + (higher.clone() - lower.clone()) / denom.clone()
     }
+    private_impl! {}
 }
 
 impl<T> Interpolate<T> for Linear
@@ -135,4 +141,5 @@ where
         let higher_f64 = higher.to_f64().unwrap();
         lower.clone() + T::from_f64(fraction * (higher_f64 - lower_f64)).unwrap()
     }
+    private_impl! {}
 }

src/quantile/mod.rs

@@ -295,6 +295,8 @@ where
         A::NotNan: Clone + Ord,
         S: DataMut,
         I: Interpolate<A::NotNan>;
+
+    private_decl! {}
 }
 
 impl<A, S, D> QuantileExt<A, S, D> for ArrayBase<S, D>
@@ -568,6 +570,8 @@ where
         });
         Ok(quantile)
     }
+
+    private_impl! {}
 }
 
 /// Quantile methods for 1-D arrays.
@@ -635,6 +639,8 @@ where
         S: DataMut,
         S2: Data<Elem = N64>,
         I: Interpolate<A>;
+
+    private_decl! {}
 }
 
 impl<A, S> Quantile1dExt<A, S> for ArrayBase<S, Ix1>
@@ -665,6 +671,8 @@ where
     {
         self.quantiles_axis_mut(Axis(0), qs, interpolate)
     }
+
+    private_impl! {}
 }
 
 pub mod interpolate;

src/sort.rs

@@ -103,6 +103,8 @@ where
     where
         A: Ord + Clone,
         S: DataMut;
+
+    private_decl! {}
 }
 
 impl<A, S> Sort1dExt<A, S> for ArrayBase<S, Ix1>
@@ -183,6 +185,8 @@ where
         self.swap(0, i - 1);
         i - 1
     }
+
+    private_impl! {}
 }
 
 /// To retrieve multiple indexes from the sorted array in an optimized fashion,

src/summary_statistics/means.rs

@@ -105,6 +105,8 @@ where
             }
         }
     }
+
+    private_impl! {}
 }
 
 /// Returns a vector containing all moments of the array elements up to

src/summary_statistics/mod.rs

@@ -140,6 +140,8 @@ where
     fn central_moments(&self, order: u16) -> Result<Vec<A>, EmptyInput>
     where
         A: Float + FromPrimitive;
+
+    private_decl! {}
 }
 
 mod means;