Merge #563

563: Introduce `num_coords` method on all geometry types. r=michaelkirk a=frewsxcv

I'm going to use these methods in a project to preallocate vectors of
coordinates.


- [x] I agree to follow the project's [code of conduct](https://github.com/georust/geo/blob/master/CODE_OF_CONDUCT.md).
- [x] I added an entry to `CHANGES.md` if knowledge of this change could be valuable to users.
---

Co-authored-by: Corey Farwell <coreyf@rwell.org>

Author: bors[bot]

geo-types/CHANGES.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+* `geo_types::LineString::num_coords` has been deprecated in favor of `geo::algorithm::coords_iter::CoordsIter::coords_count`
+  * <https://github.com/georust/geo/pull/563>
+
 ## 0.6.2
 
 * Add `into_iter`, `iter` and `iter_mut` methods for `MultiPolygon`, `MultiPoint`, and `MultiLineString`

geo-types/src/line_string.rs

@@ -201,6 +201,7 @@ impl<T: CoordinateType> LineString<T> {
     /// let line_string: LineString<f32> = coords.into_iter().collect();
     /// assert_eq!(3, line_string.num_coords());
     /// ```
+    #[deprecated(note = "Use geo::algorithm::coords_iter::CoordsIter::coords_count instead")]
     pub fn num_coords(&self) -> usize {
         self.0.len()
     }

geo/CHANGES.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+* Introduce `coords_count` method on `CoordsIter`.
+  * <https://github.com/georust/geo/pull/563>
 * Fix non-empty MultiPoint has 0-dimensions, not 1.
   * <https://github.com/georust/geo/pull/561>
 

geo/src/algorithm/coords_iter.rs

@@ -33,6 +33,24 @@ pub trait CoordsIter<'a, T: CoordinateType> {
     /// assert_eq!(None, iter.next());
     /// ```
     fn coords_iter(&'a self) -> Self::Iter;
+
+    /// Return the number of coordinates in a geometry.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use geo::coords_iter::CoordsIter;
+    /// use geo::line_string;
+    ///
+    /// let ls = line_string![
+    ///     (x: 1., y: 2.),
+    ///     (x: 23., y: 82.),
+    ///     (x: -1., y: 0.),
+    /// ];
+    ///
+    /// assert_eq!(3, ls.coords_count());
+    /// ```
+    fn coords_count(&'a self) -> usize;
 }
 
 // ┌──────────────────────────┐
@@ -45,6 +63,11 @@ impl<'a, T: CoordinateType> CoordsIter<'a, T> for Point<T> {
     fn coords_iter(&'a self) -> Self::Iter {
         iter::once(self.0)
     }
+
+    /// Return the number of coordinates in the `Point`.
+    fn coords_count(&'a self) -> usize {
+        1
+    }
 }
 
 // ┌─────────────────────────┐
@@ -57,6 +80,11 @@ impl<'a, T: CoordinateType> CoordsIter<'a, T> for Line<T> {
     fn coords_iter(&'a self) -> Self::Iter {
         iter::once(self.start).chain(iter::once(self.end))
     }
+
+    /// Return the number of coordinates in the `Line`.
+    fn coords_count(&'a self) -> usize {
+        2
+    }
 }
 
 // ┌───────────────────────────────┐
@@ -69,6 +97,11 @@ impl<'a, T: CoordinateType + 'a> CoordsIter<'a, T> for LineString<T> {
     fn coords_iter(&'a self) -> Self::Iter {
         self.0.iter().copied()
     }
+
+    /// Return the number of coordinates in the `LineString`.
+    fn coords_count(&'a self) -> usize {
+        self.0.len()
+    }
 }
 
 // ┌────────────────────────────┐
@@ -87,6 +120,12 @@ impl<'a, T: CoordinateType + 'a> CoordsIter<'a, T> for Polygon<T> {
             .coords_iter()
             .chain(MapCoordsIter(self.interiors().iter(), marker::PhantomData).flatten())
     }
+
+    /// Return the number of coordinates in the `Polygon`.
+    fn coords_count(&'a self) -> usize {
+        self.exterior().coords_count() +
+            self.interiors().iter().map(|i| i.coords_count()).sum::<usize>()
+    }
 }
 
 // ┌───────────────────────────────┐
@@ -99,6 +138,11 @@ impl<'a, T: CoordinateType + 'a> CoordsIter<'a, T> for MultiPoint<T> {
     fn coords_iter(&'a self) -> Self::Iter {
         MapCoordsIter(self.0.iter(), marker::PhantomData).flatten()
     }
+
+    /// Return the number of coordinates in the `MultiPoint`.
+    fn coords_count(&'a self) -> usize {
+        self.0.len()
+    }
 }
 
 // ┌────────────────────────────────────┐
@@ -111,6 +155,11 @@ impl<'a, T: CoordinateType + 'a> CoordsIter<'a, T> for MultiLineString<T> {
     fn coords_iter(&'a self) -> Self::Iter {
         MapCoordsIter(self.0.iter(), marker::PhantomData).flatten()
     }
+
+    /// Return the number of coordinates in the `MultiLineString`.
+    fn coords_count(&'a self) -> usize {
+        self.0.iter().map(|line_string| line_string.coords_count()).sum()
+    }
 }
 
 // ┌─────────────────────────────────┐
@@ -123,6 +172,11 @@ impl<'a, T: CoordinateType + 'a> CoordsIter<'a, T> for MultiPolygon<T> {
     fn coords_iter(&'a self) -> Self::Iter {
         MapCoordsIter(self.0.iter(), marker::PhantomData).flatten()
     }
+
+    /// Return the number of coordinates in the `MultiPolygon`.
+    fn coords_count(&'a self) -> usize {
+        self.0.iter().map(|polygon| polygon.coords_count()).sum()
+    }
 }
 
 // ┌───────────────────────────────────────┐
@@ -135,6 +189,11 @@ impl<'a, T: CoordinateType + 'a> CoordsIter<'a, T> for GeometryCollection<T> {
     fn coords_iter(&'a self) -> Self::Iter {
         Box::new(self.0.iter().flat_map(|geometry| geometry.coords_iter()))
     }
+
+    /// Return the number of coordinates in the `GeometryCollection`.
+    fn coords_count(&'a self) -> usize {
+        self.0.iter().map(|geometry| geometry.coords_count()).sum()
+    }
 }
 
 // ┌─────────────────────────┐
@@ -167,6 +226,14 @@ impl<'a, T: CoordinateType + 'a> CoordsIter<'a, T> for Rect<T> {
             y: self.min().y,
         }))
     }
+
+    /// Return the number of coordinates in the `Rect`.
+    ///
+    /// Note: Although a `Rect` is represented by two coordinates, it is
+    /// spatially represented by four, so this method returns `4`.
+    fn coords_count(&'a self) -> usize {
+        4
+    }
 }
 
 // ┌─────────────────────────────┐
@@ -181,6 +248,11 @@ impl<'a, T: CoordinateType + 'a> CoordsIter<'a, T> for Triangle<T> {
             .chain(iter::once(self.1))
             .chain(iter::once(self.2))
     }
+
+    /// Return the number of coordinates in the `Triangle`.
+    fn coords_count(&'a self) -> usize {
+        3
+    }
 }
 
 // ┌─────────────────────────────┐
@@ -206,6 +278,22 @@ impl<'a, T: CoordinateType + 'a> CoordsIter<'a, T> for Geometry<T> {
             Geometry::Triangle(g) => GeometryCoordsIter::Triangle(g.coords_iter()),
         }
     }
+
+    /// Return the number of coordinates in the `Geometry`.
+    fn coords_count(&'a self) -> usize {
+        match self {
+            Geometry::Point(g) => g.coords_count(),
+            Geometry::Line(g) => g.coords_count(),
+            Geometry::LineString(g) => g.coords_count(),
+            Geometry::Polygon(g) => g.coords_count(),
+            Geometry::MultiPoint(g) => g.coords_count(),
+            Geometry::MultiLineString(g) => g.coords_count(),
+            Geometry::MultiPolygon(g) => g.coords_count(),
+            Geometry::GeometryCollection(g) => g.coords_count(),
+            Geometry::Rect(g) => g.coords_count(),
+            Geometry::Triangle(g) => g.coords_count(),
+        }
+    }
 }
 
 // ┌───────────┐

geo/src/algorithm/frechet_distance.rs

@@ -1,3 +1,4 @@
+use crate::coords_iter::CoordsIter;
 use crate::euclidean_distance::EuclideanDistance;
 use crate::{LineString, Point};
 use num_traits::{Float, FromPrimitive};
@@ -45,13 +46,13 @@ where
     T: Float + FromPrimitive,
 {
     fn frechet_distance(&self, ls: &LineString<T>) -> T {
-        if self.num_coords() != 0 && ls.num_coords() != 0 {
+        if self.coords_count() != 0 && ls.coords_count() != 0 {
             let mut data = Data {
-                cache: vec![vec![T::nan(); ls.num_coords()]; self.num_coords()],
+                cache: vec![vec![T::nan(); ls.coords_count()]; self.coords_count()],
                 ls_a: self,
                 ls_b: ls,
             };
-            data.compute(self.num_coords() - 1, ls.num_coords() - 1)
+            data.compute(self.coords_count() - 1, ls.coords_count() - 1)
         } else {
             T::zero()
         }

geo/src/algorithm/line_interpolate_point.rs

@@ -1,3 +1,4 @@
+use crate::coords_iter::CoordsIter;
 use num_traits::Float;
 use std::ops::AddAssign;
 
@@ -93,7 +94,7 @@ where
             }
             // either cum_length + length is never larger than fractional_length, i.e.
             // fractional_length is nan, or the linestring has no lines to loop through
-            debug_assert!(fractional_length.is_nan() || (self.num_coords() == 0));
+            debug_assert!(fractional_length.is_nan() || (self.coords_count() == 0));
             None
         } else if fraction < T::zero() {
             // negative fractions replaced with zero

geo/src/algorithm/winding_order.rs

@@ -1,4 +1,5 @@
 use super::kernels::*;
+use crate::coords_iter::CoordsIter;
 use crate::utils::EitherIter;
 use crate::{CoordinateType, LineString, Point};
 use geo_types::PointsIter;
@@ -101,20 +102,20 @@ where
         // If linestring has at most 3 coords, it is either
         // not closed, or is at most two distinct points.
         // Either way, the WindingOrder is unspecified.
-        if self.num_coords() < 4 || !self.is_closed() {
+        if self.coords_count() < 4 || !self.is_closed() {
             return None;
         }
 
         let increment = |x: &mut usize| {
             *x += 1;
-            if *x >= self.num_coords() {
+            if *x >= self.coords_count() {
                 *x = 0;
             }
         };
 
         let decrement = |x: &mut usize| {
             if *x == 0 {
-                *x = self.num_coords() - 1;
+                *x = self.coords_count() - 1;
             } else {
                 *x -= 1;
             }