refactor(library): Introduce Polyline and Polygon type aliases

dkhawk · dkhawk · commit 177bab958d12 · 2025-09-05T15:04:24.000-06:00
This commit introduces `Polyline` and `Polygon` as type aliases for `List&lt;LatLng&gt;` to improve code readability and provide stronger semantic meaning. This change makes it explicit whether a list of coordinates represents a line or a closed area.

The following files and classes have been updated to use these new type aliases:
- `PolyUtil`: Functions now accept `Polyline` or `Polygon` instead of a generic `List&lt;LatLng&gt;`.
- `SphericalUtil`: `computeLength` and `computeArea` now operate on `Polyline` and `Polygon` respectively.
- `LineString`: The `coordinates` property is now of type `Polyline`.
- `DataPolygon`: Boundary properties now use the `Polygon` type alias.
diff --git a/library/src/main/java/com/google/maps/android/PolyUtil.kt b/library/src/main/java/com/google/maps/android/PolyUtil.kt
@@ -17,6 +17,8 @@
 package com.google.maps.android
 
 import com.google.android.gms.maps.model.LatLng
+import com.google.maps.android.data.Polygon
+import com.google.maps.android.data.Polyline
 import com.google.maps.android.MathUtil.clamp
 import com.google.maps.android.MathUtil.hav
 import com.google.maps.android.MathUtil.havDistance
@@ -62,7 +64,7 @@ object PolyUtil {
      * @return `true` if the point is inside the polygon, `false` otherwise.
      */
     @JvmStatic
-    fun containsLocation(point: LatLng, polygon: List<LatLng>, geodesic: Boolean): Boolean {
+    fun containsLocation(point: LatLng, polygon: Polygon, geodesic: Boolean): Boolean {
         return containsLocation(point.latitude, point.longitude, polygon, geodesic)
     }
 
@@ -74,7 +76,7 @@ object PolyUtil {
     fun containsLocation(
         latitude: Double,
         longitude: Double,
-        polygon: List<LatLng>,
+        polygon: Polygon,
         geodesic: Boolean
     ): Boolean {
         if (polygon.isEmpty()) {
@@ -122,7 +124,7 @@ object PolyUtil {
     @JvmOverloads
     fun isLocationOnEdge(
         point: LatLng,
-        polygon: List<LatLng>,
+        polygon: Polygon,
         geodesic: Boolean,
         tolerance: Double = DEFAULT_TOLERANCE
     ): Boolean {
@@ -145,7 +147,7 @@ object PolyUtil {
     @JvmOverloads
     fun isLocationOnPath(
         point: LatLng,
-        polyline: List<LatLng>,
+        polyline: Polyline,
         geodesic: Boolean,
         tolerance: Double = DEFAULT_TOLERANCE
     ): Boolean {
@@ -154,12 +156,12 @@ object PolyUtil {
 
     private fun isLocationOnEdgeOrPath(
         point: LatLng,
-        poly: List<LatLng>,
+        polyline: Polyline,
         closed: Boolean,
         geodesic: Boolean,
         toleranceEarth: Double
     ): Boolean {
-        val idx = locationIndexOnEdgeOrPath(point, poly, closed, geodesic, toleranceEarth)
+        val idx = locationIndexOnEdgeOrPath(point, polyline, closed, geodesic, toleranceEarth)
 
         return (idx >= 0)
     }
@@ -183,7 +185,7 @@ object PolyUtil {
     @JvmOverloads
     fun locationIndexOnPath(
         point: LatLng,
-        poly: List<LatLng>,
+        poly: Polyline,
         geodesic: Boolean,
         tolerance: Double = DEFAULT_TOLERANCE
     ): Int {
@@ -209,7 +211,7 @@ object PolyUtil {
     @JvmStatic
     fun locationIndexOnEdgeOrPath(
         point: LatLng,
-        poly: List<LatLng>,
+        poly: Polyline,
         closed: Boolean,
         geodesic: Boolean,
         toleranceEarth: Double
@@ -299,8 +301,8 @@ object PolyUtil {
      * simplified poly.
      * @return a simplified poly produced by the Douglas-Peucker algorithm
      */
-    @JvmStatic
-    fun simplify(poly: List<LatLng>, tolerance: Double): List<LatLng> {
+        @JvmStatic
+    fun simplify(poly: Polyline, tolerance: Double): Polyline {
         require(poly.isNotEmpty()) { "Polyline must have at least 1 point" }
         require(tolerance > 0) { "Tolerance must be greater than zero" }
 
@@ -339,13 +341,13 @@ object PolyUtil {
      * If this point is farther than the specified tolerance, it is kept, and the algorithm is
      * applied recursively to the two new segments.
      *
-     * @param poly The polyline to be simplified.
+     * @param polyline The polyline to be simplified.
      * @param tolerance The tolerance in meters.
      * @return A boolean array where `true` indicates that the point at the corresponding index
      * should be kept in the simplified polyline.
      */
-    private fun douglasPeucker(poly: List<LatLng>, tolerance: Double): BooleanArray {
-        val n = poly.size
+    private fun douglasPeucker(polyline: Polyline, tolerance: Double): BooleanArray {
+        val n = polyline.size
         // We start with a boolean array that will mark the points to keep.
         // Initially, only the first and last points are marked for keeping.
         val keepPoint = BooleanArray(n) { false }
@@ -368,7 +370,7 @@ object PolyUtil {
                 // For the current segment, we find the point that is farthest from the line
                 // connecting the start and end points.
                 for (idx in start + 1 until end) {
-                    val dist = distanceToLine(poly[idx], poly[start], poly[end])
+                    val dist = distanceToLine(polyline[idx], polyline[start], polyline[end])
                     if (dist > maxDist) {
                         maxDist = dist
                         maxIdx = idx
@@ -393,13 +395,13 @@ object PolyUtil {
      * Returns true if the provided list of points is a closed polygon (i.e., the first and last
      * points are the same), and false if it is not
      *
-     * @param poly polyline or polygon
+     * @param polyline polyline or polygon
      * @return true if the provided list of points is a closed polygon (i.e., the first and last
      * points are the same), and false if it is not
      */
     @JvmStatic
-    fun isClosedPolygon(poly: List<LatLng>): Boolean {
-        return poly.isNotEmpty() && poly.first() == poly.last()
+    fun isClosedPolygon(polyline: Polyline): Boolean {
+        return polyline.isNotEmpty() && polyline.first() == polyline.last()
     }
 
     /**
@@ -447,7 +449,7 @@ object PolyUtil {
      * Decodes an encoded path string into a sequence of LatLngs.
      */
     @JvmStatic
-    fun decode(encodedPath: String): List<LatLng> {
+    fun decode(encodedPath: String): Polyline {
         val len = encodedPath.length
         val path = mutableListOf<LatLng>()
         var index = 0
@@ -484,7 +486,7 @@ object PolyUtil {
      * Encodes a sequence of LatLngs into an encoded path string.
      */
     @JvmStatic
-    fun encode(path: List<LatLng>): String {
+    fun encode(path: Polyline): String {
         var lastLat: Long = 0
         var lastLng: Long = 0
         val result = StringBuilder()
diff --git a/library/src/main/java/com/google/maps/android/SphericalUtil.kt b/library/src/main/java/com/google/maps/android/SphericalUtil.kt
@@ -17,6 +17,8 @@
 package com.google.maps.android
 
 import com.google.android.gms.maps.model.LatLng
+import com.google.maps.android.data.Polygon
+import com.google.maps.android.data.Polyline
 import com.google.maps.android.MathUtil.EARTH_RADIUS
 import com.google.maps.android.MathUtil.arcHav
 import com.google.maps.android.MathUtil.havDistance
@@ -202,7 +204,7 @@ object SphericalUtil {
      * Returns the length of the given path, in meters, on Earth.
      */
     @JvmStatic
-    fun computeLength(path: List<LatLng>): Double {
+    fun computeLength(path: Polyline): Double {
         if (path.size < 2) {
             return 0.0
         }
@@ -228,7 +230,7 @@ object SphericalUtil {
      * @return The path's area in square meters.
      */
     @JvmStatic
-    fun computeArea(path: List<LatLng>): Double {
+    fun computeArea(path: Polygon): Double {
         return abs(computeSignedArea(path))
     }
 
@@ -241,7 +243,7 @@ object SphericalUtil {
      * @return The loop's area in square meters.
      */
     @JvmStatic
-    fun computeSignedArea(path: List<LatLng>): Double {
+    fun computeSignedArea(path: Polygon): Double {
         return computeSignedArea(path, EARTH_RADIUS)
     }
 
@@ -251,7 +253,7 @@ object SphericalUtil {
      * Used by SphericalUtilTest.
      */
     @JvmStatic
-    fun computeSignedArea(path: List<LatLng>, radius: Double): Double {
+    fun computeSignedArea(path: Polygon, radius: Double): Double {
         val size = path.size
         if (size < 3) {
             return 0.0
diff --git a/library/src/main/java/com/google/maps/android/data/DataPolygon.kt b/library/src/main/java/com/google/maps/android/data/DataPolygon.kt
@@ -28,10 +28,10 @@ interface DataPolygon<T> : Geometry<T> {
     /**
      * Gets an array of outer boundary coordinates
      */
-    val outerBoundaryCoordinates: List<LatLng>
+    val outerBoundaryCoordinates: Polygon
 
     /**
      * Gets an array of arrays of inner boundary coordinates
      */
-    val innerBoundaryCoordinates: List<List<LatLng>>
+    val innerBoundaryCoordinates: List<Polygon>
 }
diff --git a/library/src/main/java/com/google/maps/android/data/Geometry.kt b/library/src/main/java/com/google/maps/android/data/Geometry.kt
@@ -15,6 +15,18 @@
  */
 package com.google.maps.android.data
 
+import com.google.android.gms.maps.model.LatLng
+
+/**
+ * A Polyline is a list of LatLngs where each LatLng is a vertex of the line.
+ */
+typealias Polyline = List<LatLng>
+
+/**
+ * A Polygon is a list of LatLngs where each LatLng is a vertex of the polygon.
+ */
+typealias Polygon = List<LatLng>
+
 /**
  * An abstraction that represents a Geometry object
  *
diff --git a/library/src/main/java/com/google/maps/android/data/LineString.kt b/library/src/main/java/com/google/maps/android/data/LineString.kt
@@ -22,14 +22,14 @@ import com.google.android.gms.maps.model.LatLng
  * [com.google.maps.android.data.kml.KmlLineString] and
  * [com.google.maps.android.data.geojson.GeoJsonLineString]
  */
-open class LineString(coordinates: List<LatLng>) : Geometry<List<LatLng>> {
+open class LineString(coordinates: Polyline) : Geometry<Polyline> {
 
-    private val _coordinates: List<LatLng> = coordinates
+    private val _coordinates: Polyline = coordinates
 
     /**
      * Gets the coordinates of the LineString
      */
-    open val coordinates: List<LatLng>
+    open val coordinates: Polyline
         get() = _coordinates
 
     /**
@@ -40,7 +40,7 @@ open class LineString(coordinates: List<LatLng>) : Geometry<List<LatLng>> {
     /**
      * Gets the geometry object
      */
-    override val geometryObject: List<LatLng> = _coordinates
+    override val geometryObject: Polyline = _coordinates
 
     override fun equals(other: Any?): Boolean {
         if (this === other) return true
