refactor: deprecate quick collection for TryFrom (#64)

* refactor: deprecate quick collection for TryFrom

* style: update test to use tryfrom

* style: allow deprecated where exported

* docs: remove quick_collection from examples

Author: pjsier

README.md

@@ -66,7 +66,7 @@ writer.write(&kml).unwrap();
 
 ```rust
 use geo_types::{self, GeometryCollection};
-use kml::{quick_collection, Kml, types::Point};
+use kml::{Kml, types::Point};
 
 let kml_point = Point::new(1., 1., None);
 // Convert into geo_types primitives
@@ -87,8 +87,7 @@ let kml_folder_str = r#"
 </Folder>"#;
 let kml_folder: Kml<f64> = kml_folder_str.parse().unwrap();
 
-// Use the quick_collection helper to convert Kml to a geo_types::GeometryCollection
-let geom_coll: GeometryCollection<f64> = quick_collection(kml_folder).unwrap();
+let geom_coll: GeometryCollection<f64> = kml_folder.try_into().unwrap();
 ```
 
 ## Code of Conduct

src/conversion.rs

@@ -310,56 +310,75 @@ where
     }
 }
 
-fn process_kml<T>(k: Kml<T>) -> Result<Vec<geo_types::Geometry<T>>, Error>
+#[cfg_attr(docsrs, doc(cfg(feature = "geo-types")))]
+impl<T> TryFrom<Kml<T>> for Vec<geo_types::Geometry<T>>
 where
     T: CoordType,
 {
-    match k {
-        Kml::KmlDocument(d) => Ok(d
-            .elements
-            .into_iter()
-            .flat_map(process_kml)
-            .flatten()
-            .collect()),
-        Kml::Point(p) => Ok(vec![
-            geo_types::Geometry::Point(geo_types::Point::from(p));
-            1
-        ]),
-        Kml::LineString(l) => Ok(vec![
-            geo_types::Geometry::LineString(
-                geo_types::LineString::from(l),
-            );
-            1
-        ]),
-        Kml::LinearRing(l) => Ok(vec![
-            geo_types::Geometry::LineString(
-                geo_types::LineString::from(l),
-            );
-            1
-        ]),
-        Kml::Polygon(p) => Ok(vec![
-            geo_types::Geometry::Polygon(geo_types::Polygon::from(
-                p
-            ));
-            1
-        ]),
-        Kml::MultiGeometry(g) => Ok(geo_types::GeometryCollection::try_from(g)?.0),
-        Kml::Placemark(p) => Ok(if let Some(g) = p.geometry {
-            vec![geo_types::Geometry::try_from(g)?; 1]
-        } else {
-            vec![]
-        }),
-        Kml::Document { elements, .. } => Ok(elements
-            .into_iter()
-            .flat_map(process_kml)
-            .flatten()
-            .collect()),
-        Kml::Folder { elements, .. } => Ok(elements
-            .into_iter()
-            .flat_map(process_kml)
-            .flatten()
-            .collect()),
-        _ => Ok(vec![]),
+    type Error = Error;
+
+    fn try_from(k: Kml<T>) -> Result<Vec<geo_types::Geometry<T>>, Self::Error> {
+        match k {
+            Kml::KmlDocument(d) => Ok(d
+                .elements
+                .into_iter()
+                .flat_map(Vec::<geo_types::Geometry<T>>::try_from)
+                .flatten()
+                .collect::<Vec<geo_types::Geometry<T>>>()),
+            Kml::Point(p) => Ok(vec![
+                geo_types::Geometry::Point(geo_types::Point::from(p));
+                1
+            ]),
+            Kml::LineString(l) => Ok(vec![
+                geo_types::Geometry::LineString(
+                    geo_types::LineString::from(l),
+                );
+                1
+            ]),
+            Kml::LinearRing(l) => Ok(vec![
+                geo_types::Geometry::LineString(
+                    geo_types::LineString::from(l),
+                );
+                1
+            ]),
+            Kml::Polygon(p) => Ok(vec![
+                geo_types::Geometry::Polygon(geo_types::Polygon::from(
+                    p
+                ));
+                1
+            ]),
+            Kml::MultiGeometry(g) => Ok(geo_types::GeometryCollection::try_from(g)?.0),
+            Kml::Placemark(p) => Ok(if let Some(g) = p.geometry {
+                vec![geo_types::Geometry::try_from(g)?; 1]
+            } else {
+                vec![]
+            }),
+            Kml::Document { elements, .. } => Ok(elements
+                .into_iter()
+                .flat_map(Vec::<geo_types::Geometry<T>>::try_from)
+                .flatten()
+                .collect()),
+            Kml::Folder { elements, .. } => Ok(elements
+                .into_iter()
+                .flat_map(Vec::<geo_types::Geometry<T>>::try_from)
+                .flatten()
+                .collect()),
+            _ => Ok(vec![]),
+        }
+    }
+}
+
+#[cfg_attr(docsrs, doc(cfg(feature = "geo-types")))]
+impl<T> TryFrom<Kml<T>> for geo_types::GeometryCollection<T>
+where
+    T: CoordType,
+{
+    type Error = Error;
+
+    fn try_from(k: Kml<T>) -> Result<geo_types::GeometryCollection<T>, Self::Error> {
+        Ok(geo_types::GeometryCollection(
+            Vec::<geo_types::Geometry<T>>::try_from(k)?,
+        ))
     }
 }
 
@@ -387,12 +406,16 @@ where
 /// // Turn the KML string into a geo_types GeometryCollection
 /// let mut collection: GeometryCollection<f64> = quick_collection(k).unwrap();
 /// ```
+#[deprecated(
+    since = "0.8.7",
+    note = "use `geo_types::GeometryCollection::try_from(&k)` instead"
+)]
 #[cfg_attr(docsrs, doc(cfg(feature = "geo-types")))]
 pub fn quick_collection<T>(k: Kml<T>) -> Result<geo_types::GeometryCollection<T>, Error>
 where
     T: CoordType,
 {
-    Ok(geo_types::GeometryCollection(process_kml(k)?))
+    geo_types::GeometryCollection::try_from(k)
 }
 
 #[cfg(test)]
@@ -402,7 +425,7 @@ mod tests {
     use std::collections::HashMap;
 
     #[test]
-    fn test_quick_collection() {
+    fn test_try_from_collection() {
         let k = KmlDocument {
             elements: vec![
                 Kml::Point(Point::from(Coord::from((1., 1.)))),
@@ -425,6 +448,9 @@ mod tests {
             geo_types::Geometry::LineString(geo_types::LineString::from(vec![(1., 1.), (2., 2.)])),
             geo_types::Geometry::Point(geo_types::Point::from((3., 3.))),
         ]);
-        assert_eq!(quick_collection(Kml::KmlDocument(k)).unwrap(), gc);
+        assert_eq!(
+            geo_types::GeometryCollection::try_from(Kml::KmlDocument(k)).unwrap(),
+            gc
+        );
     }
 }

src/lib.rs

@@ -67,7 +67,7 @@
 //! ```
 //! # #[cfg(feature = "geo-types")] {
 //! use geo_types::{self, GeometryCollection};
-//! use kml::{quick_collection, Kml, types::Point};
+//! use kml::{Kml, types::Point};
 //!
 //! let kml_point = Point::new(1., 1., None);
 //! // Convert into geo_types primitives
@@ -88,8 +88,7 @@
 //! </Folder>"#;
 //! let kml_folder: Kml<f64> = kml_folder_str.parse().unwrap();
 //!
-//! // Use the quick_collection helper to convert Kml to a geo_types::GeometryCollection
-//! let geom_coll: GeometryCollection<f64> = quick_collection(kml_folder).unwrap();
+//! let geom_coll: GeometryCollection<f64> = kml_folder.try_into().unwrap();
 //! # }
 //! ```
 
@@ -112,6 +111,7 @@ pub use crate::writer::KmlWriter;
 pub mod conversion;
 
 #[cfg(feature = "geo-types")]
+#[allow(deprecated)]
 pub use conversion::quick_collection;
 
 #[cfg(feature = "zip")]