Add geo-traits crate

.github/workflows/test.yml

@@ -118,6 +118,32 @@ jobs:
       # we don't want to test `proj-network` because it only enables the `proj` feature
       - run: cargo test --features "use-proj use-serde"
 
+  geo_traits:
+    name: geo-traits
+    runs-on: ubuntu-latest
+    if: "!contains(github.event.head_commit.message, '[skip ci]')"
+    defaults:
+      run:
+        working-directory: geo-traits
+    strategy:
+      matrix:
+        container_image:
+          # We aim to support rust-stable plus (at least) the prior 3 releases,
+          # giving us about 6 months of coverage.
+          #
+          # Minimum supported rust version (MSRV)
+          - "ghcr.io/georust/geo-ci:proj-9.4.0-rust-1.75"
+          # Two most recent releases - we omit older ones for expedient CI
+          - "ghcr.io/georust/geo-ci:proj-9.4.0-rust-1.78"
+          - "ghcr.io/georust/geo-ci:proj-9.4.0-rust-1.79"
+    container:
+      image: ${{ matrix.container_image }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v2
+      - run: cargo check --all-targets
+      - run: cargo test
+
   geo_postgis:
     name: geo-postgis
     runs-on: ubuntu-latest
@@ -184,4 +210,3 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v3
       - run: RUSTDOCFLAGS="-D warnings" cargo doc --all-features --no-deps
-

Cargo.toml

@@ -2,11 +2,12 @@
 resolver = "2"
 members = [
   "geo",
-  "geo-types",
+  "geo-bool-ops-benches",
   "geo-postgis",
   "geo-test-fixtures",
+  "geo-traits",
+  "geo-types",
   "jts-test-runner",
-  "geo-bool-ops-benches",
 ]
 
 [patch.crates-io]

geo-traits/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "geo-traits"
+version = "0.1.0"
+license = "MIT OR Apache-2.0"
+repository = "https://github.com/georust/geo"
+documentation = "https://docs.rs/geo-traits/"
+readme = "../README.md"
+keywords = ["gis", "geo", "geography", "geospatial"]
+description = "Geospatial traits"
+rust-version = "1.65"
+edition = "2021"
+
+[dependencies]
+geo-types = "0.7"
+
+[dev-dependencies]

geo-traits/src/dimension.rs

@@ -0,0 +1,34 @@
+/// The logical dimension of the geometry.
+///
+///
+#[allow(clippy::upper_case_acronyms)]
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+pub enum Dimension {
+    /// A two-dimensional geometry with X and Y values
+    XY,
+
+    /// A three-dimensional geometry with X, Y, and Z values
+    XYZ,
+
+    /// A three-dimensional geometry with X, Y, and M values
+    XYM,
+
+    /// A four-dimensional geometry with X, Y, Z, and M values
+    XYZM,
+
+    /// A geometry with unknown logical type. The contained `usize` value represents the number of
+    /// physical dimensions.
+    Unknown(usize),
+}
+
+impl Dimension {
+    /// The physical number of dimensions in this geometry.
+    pub fn size(&self) -> usize {
+        match self {
+            Self::XY => 2,
+            Self::XYZ | Self::XYM => 3,
+            Self::XYZM => 4,
+            Self::Unknown(val) => *val,
+        }
+    }
+}

geo-traits/src/geometry.rs

@@ -0,0 +1,191 @@
+use geo_types::{
+    CoordNum, Geometry, GeometryCollection, LineString, MultiLineString, MultiPoint, MultiPolygon,
+    Point, Polygon, Rect,
+};
+
+use crate::{
+    Dimension, GeometryCollectionTrait, LineStringTrait, MultiLineStringTrait, MultiPointTrait,
+    MultiPolygonTrait, PointTrait, PolygonTrait, RectTrait,
+};
+
+/// A trait for accessing data from a generic Geometry.
+#[allow(clippy::type_complexity)]
+pub trait GeometryTrait {
+    /// The coordinate type of this geometry
+    type T: CoordNum;
+
+    /// The type of each underlying Point, which implements [PointTrait]
+    type Point<'a>: 'a + PointTrait<T = Self::T>
+    where
+        Self: 'a;
+
+    /// The type of each underlying LineString, which implements [LineStringTrait]
+    type LineString<'a>: 'a + LineStringTrait<T = Self::T>
+    where
+        Self: 'a;
+
+    /// The type of each underlying Polygon, which implements [PolygonTrait]
+    type Polygon<'a>: 'a + PolygonTrait<T = Self::T>
+    where
+        Self: 'a;
+
+    /// The type of each underlying MultiPoint, which implements [MultiPointTrait]
+    type MultiPoint<'a>: 'a + MultiPointTrait<T = Self::T>
+    where
+        Self: 'a;
+
+    /// The type of each underlying MultiLineString, which implements [MultiLineStringTrait]
+    type MultiLineString<'a>: 'a + MultiLineStringTrait<T = Self::T>
+    where
+        Self: 'a;
+
+    /// The type of each underlying MultiPolygon, which implements [MultiPolygonTrait]
+    type MultiPolygon<'a>: 'a + MultiPolygonTrait<T = Self::T>
+    where
+        Self: 'a;
+
+    /// The type of each underlying GeometryCollection, which implements [GeometryCollectionTrait]
+    type GeometryCollection<'a>: 'a + GeometryCollectionTrait<T = Self::T>
+    where
+        Self: 'a;
+
+    /// The type of each underlying Rect, which implements [RectTrait]
+    type Rect<'a>: 'a + RectTrait<T = Self::T>
+    where
+        Self: 'a;
+
+    /// The dimension of this geometry
+    fn dim(&self) -> Dimension;
+
+    /// Cast this geometry to a [`GeometryType`] enum, which allows for downcasting to a specific
+    /// type
+    fn as_type(
+        &self,
+    ) -> GeometryType<
+        '_,
+        Self::Point<'_>,
+        Self::LineString<'_>,
+        Self::Polygon<'_>,
+        Self::MultiPoint<'_>,
+        Self::MultiLineString<'_>,
+        Self::MultiPolygon<'_>,
+        Self::GeometryCollection<'_>,
+        Self::Rect<'_>,
+    >;
+}
+
+/// An enumeration of all geometry types that can be contained inside a [GeometryTrait]. This is
+/// used for extracting concrete geometry types out of a [GeometryTrait].
+#[derive(Debug)]
+pub enum GeometryType<'a, P, L, Y, MP, ML, MY, GC, R>
+where
+    P: PointTrait,
+    L: LineStringTrait,
+    Y: PolygonTrait,
+    MP: MultiPointTrait,
+    ML: MultiLineStringTrait,
+    MY: MultiPolygonTrait,
+    GC: GeometryCollectionTrait,
+    R: RectTrait,
+{
+    /// A Point, which implements [PointTrait]
+    Point(&'a P),
+    /// A LineString, which implements [LineStringTrait]
+    LineString(&'a L),
+    /// A Polygon, which implements [PolygonTrait]
+    Polygon(&'a Y),
+    /// A MultiPoint, which implements [MultiPointTrait]
+    MultiPoint(&'a MP),
+    /// A MultiLineString, which implements [MultiLineStringTrait]
+    MultiLineString(&'a ML),
+    /// A MultiPolygon, which implements [MultiPolygonTrait]
+    MultiPolygon(&'a MY),
+    /// A GeometryCollection, which implements [GeometryCollectionTrait]
+    GeometryCollection(&'a GC),
+    /// A Rect, which implements [RectTrait]
+    Rect(&'a R),
+}
+
+impl<'a, T: CoordNum + 'a> GeometryTrait for Geometry<T> {
+    type T = T;
+    type Point<'b> = Point<Self::T> where Self: 'b;
+    type LineString<'b> = LineString<Self::T> where Self: 'b;
+    type Polygon<'b> = Polygon<Self::T> where Self: 'b;
+    type MultiPoint<'b> = MultiPoint<Self::T> where Self: 'b;
+    type MultiLineString<'b> = MultiLineString<Self::T> where Self: 'b;
+    type MultiPolygon<'b> = MultiPolygon<Self::T> where Self: 'b;
+    type GeometryCollection<'b> = GeometryCollection<Self::T> where Self: 'b;
+    type Rect<'b> = Rect<Self::T> where Self: 'b;
+
+    fn dim(&self) -> Dimension {
+        Dimension::XY
+    }
+
+    fn as_type(
+        &self,
+    ) -> GeometryType<
+        '_,
+        Point<T>,
+        LineString<T>,
+        Polygon<T>,
+        MultiPoint<T>,
+        MultiLineString<T>,
+        MultiPolygon<T>,
+        GeometryCollection<T>,
+        Rect<T>,
+    > {
+        match self {
+            Geometry::Point(p) => GeometryType::Point(p),
+            Geometry::LineString(p) => GeometryType::LineString(p),
+            Geometry::Polygon(p) => GeometryType::Polygon(p),
+            Geometry::MultiPoint(p) => GeometryType::MultiPoint(p),
+            Geometry::MultiLineString(p) => GeometryType::MultiLineString(p),
+            Geometry::MultiPolygon(p) => GeometryType::MultiPolygon(p),
+            Geometry::GeometryCollection(p) => GeometryType::GeometryCollection(p),
+            Geometry::Rect(p) => GeometryType::Rect(p),
+            _ => todo!(),
+        }
+    }
+}
+
+impl<'a, T: CoordNum + 'a> GeometryTrait for &'a Geometry<T> {
+    type T = T;
+    type Point<'b> = Point<Self::T> where Self: 'b;
+    type LineString<'b> = LineString<Self::T> where Self: 'b;
+    type Polygon<'b> = Polygon<Self::T> where Self: 'b;
+    type MultiPoint<'b> = MultiPoint<Self::T> where Self: 'b;
+    type MultiLineString<'b> = MultiLineString<Self::T> where Self: 'b;
+    type MultiPolygon<'b> = MultiPolygon<Self::T> where Self: 'b;
+    type GeometryCollection<'b> = GeometryCollection<Self::T> where Self: 'b;
+    type Rect<'b> = Rect<Self::T> where Self: 'b;
+
+    fn dim(&self) -> Dimension {
+        Dimension::XY
+    }
+
+    fn as_type(
+        &self,
+    ) -> GeometryType<
+        '_,
+        Point<T>,
+        LineString<T>,
+        Polygon<T>,
+        MultiPoint<T>,
+        MultiLineString<T>,
+        MultiPolygon<T>,
+        GeometryCollection<T>,
+        Rect<T>,
+    > {
+        match self {
+            Geometry::Point(p) => GeometryType::Point(p),
+            Geometry::LineString(p) => GeometryType::LineString(p),
+            Geometry::Polygon(p) => GeometryType::Polygon(p),
+            Geometry::MultiPoint(p) => GeometryType::MultiPoint(p),
+            Geometry::MultiLineString(p) => GeometryType::MultiLineString(p),
+            Geometry::MultiPolygon(p) => GeometryType::MultiPolygon(p),
+            Geometry::GeometryCollection(p) => GeometryType::GeometryCollection(p),
+            Geometry::Rect(p) => GeometryType::Rect(p),
+            _ => todo!(),
+        }
+    }
+}

geo-traits/src/geometry_collection.rs

@@ -0,0 +1,78 @@
+use crate::{Dimension, GeometryCollectionIterator, GeometryTrait};
+use geo_types::{CoordNum, Geometry, GeometryCollection};
+
+/// A trait for accessing data from a generic GeometryCollection.
+pub trait GeometryCollectionTrait: Sized {
+    /// The coordinate type of this geometry
+    type T: CoordNum;
+
+    /// The type of each underlying geometry, which implements [GeometryTrait]
+    type ItemType<'a>: 'a + GeometryTrait<T = Self::T>
+    where
+        Self: 'a;
+
+    /// The dimension of this geometry
+    fn dim(&self) -> Dimension;
+
+    /// An iterator over the geometries in this GeometryCollection
+    fn geometries(&self) -> GeometryCollectionIterator<'_, Self::T, Self::ItemType<'_>, Self> {
+        GeometryCollectionIterator::new(self, 0, self.num_geometries())
+    }
+
+    /// The number of geometries in this GeometryCollection
+    fn num_geometries(&self) -> usize;
+
+    /// Access to a specified geometry in this GeometryCollection
+    /// Will return None if the provided index is out of bounds
+    fn geometry(&self, i: usize) -> Option<Self::ItemType<'_>> {
+        if i >= self.num_geometries() {
+            None
+        } else {
+            unsafe { Some(self.geometry_unchecked(i)) }
+        }
+    }
+
+    /// Access to a specified geometry in this GeometryCollection
+    ///
+    /// # Safety
+    ///
+    /// Accessing an index out of bounds is UB.
+    unsafe fn geometry_unchecked(&self, i: usize) -> Self::ItemType<'_>;
+}
+
+impl<T: CoordNum> GeometryCollectionTrait for GeometryCollection<T> {
+    type T = T;
+    type ItemType<'a> = &'a Geometry<Self::T>
+    where
+        Self: 'a;
+
+    fn dim(&self) -> Dimension {
+        Dimension::XY
+    }
+
+    fn num_geometries(&self) -> usize {
+        self.0.len()
+    }
+
+    unsafe fn geometry_unchecked(&self, i: usize) -> Self::ItemType<'_> {
+        self.0.get_unchecked(i)
+    }
+}
+
+impl<'a, T: CoordNum> GeometryCollectionTrait for &'a GeometryCollection<T> {
+    type T = T;
+    type ItemType<'b> = &'a Geometry<Self::T> where
+        Self: 'b;
+
+    fn dim(&self) -> Dimension {
+        Dimension::XY
+    }
+
+    fn num_geometries(&self) -> usize {
+        self.0.len()
+    }
+
+    unsafe fn geometry_unchecked(&self, i: usize) -> Self::ItemType<'_> {
+        self.0.get_unchecked(i)
+    }
+}