From 4c7321f930dc43c663daa4ff39073f63b275a944 Mon Sep 17 00:00:00 2001 From: Kyle Barron Date: Tue, 27 Aug 2024 21:45:58 -0400 Subject: [PATCH] Document the geo-traits mod --- src/geo_traits/coord.rs | 1 + src/geo_traits/dimension.rs | 60 --------------------------- src/geo_traits/geometry.rs | 28 +++++++++++++ src/geo_traits/geometry_collection.rs | 4 ++ src/geo_traits/iterator.rs | 1 + src/geo_traits/line_string.rs | 4 ++ src/geo_traits/mod.rs | 2 - src/geo_traits/multi_line_string.rs | 4 ++ src/geo_traits/multi_point.rs | 4 ++ src/geo_traits/multi_polygon.rs | 4 ++ src/geo_traits/point.rs | 1 + src/geo_traits/polygon.rs | 4 ++ src/geo_traits/rect.rs | 6 +++ 13 files changed, 61 insertions(+), 62 deletions(-) delete mode 100644 src/geo_traits/dimension.rs diff --git a/src/geo_traits/coord.rs b/src/geo_traits/coord.rs index a2ca5b5c..db378ccb 100644 --- a/src/geo_traits/coord.rs +++ b/src/geo_traits/coord.rs @@ -2,6 +2,7 @@ use geo::{Coord, CoordNum, Point}; /// A trait for accessing data from a generic Coord. pub trait CoordTrait { + /// The coordinate type of this geometry type T: CoordNum; /// Access the n'th (0-based) element of the CoordinateTuple. diff --git a/src/geo_traits/dimension.rs b/src/geo_traits/dimension.rs deleted file mode 100644 index e42ce589..00000000 --- a/src/geo_traits/dimension.rs +++ /dev/null @@ -1,60 +0,0 @@ -#![allow(clippy::upper_case_acronyms)] - -use geo::CoordNum; - -pub trait DimensionXY { - type T: CoordNum; - - fn x(&self) -> Self::T; - fn y(&self) -> Self::T; -} - -pub trait DimensionXYZ: DimensionXY { - fn z(&self) -> Self::T; -} - -pub trait Test1 {} - -pub const xy: usize = 1; - -pub struct A {} -impl Test1 for A {} - -pub trait Dimension2 { - const HAS_Z: bool; - const HAS_M: bool; -} - -pub struct XY {} -pub struct XYZ {} -pub struct XYM {} -pub struct XYZM {} - -impl Dimension2 for XY { - const HAS_Z: bool = false; - const HAS_M: bool = false; -} -impl Dimension2 for XYZ { - const HAS_Z: bool = true; - const HAS_M: bool = false; -} -impl Dimension2 for XYM { - const HAS_Z: bool = false; - const HAS_M: bool = true; -} -impl Dimension2 for XYZM { - const HAS_Z: bool = true; - const HAS_M: bool = true; -} - -// https://rust-lang.github.io/api-guidelines/future-proofing.html#sealed-traits-protect-against-downstream-implementations-c-sealed -mod private { - use super::*; - - pub trait Sealed {} - - impl Sealed for XY {} - impl Sealed for XYZ {} - impl Sealed for XYM {} - impl Sealed for XYZM {} -} diff --git a/src/geo_traits/geometry.rs b/src/geo_traits/geometry.rs index 73a2c855..d8febe7a 100644 --- a/src/geo_traits/geometry.rs +++ b/src/geo_traits/geometry.rs @@ -11,34 +11,54 @@ use super::{ /// 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 where Self: 'a; + + /// The type of each underlying LineString, which implements [LineStringTrait] type LineString<'a>: 'a + LineStringTrait where Self: 'a; + + /// The type of each underlying Polygon, which implements [PolygonTrait] type Polygon<'a>: 'a + PolygonTrait where Self: 'a; + + /// The type of each underlying MultiPoint, which implements [MultiPointTrait] type MultiPoint<'a>: 'a + MultiPointTrait where Self: 'a; + + /// The type of each underlying MultiLineString, which implements [MultiLineStringTrait] type MultiLineString<'a>: 'a + MultiLineStringTrait where Self: 'a; + + /// The type of each underlying MultiPolygon, which implements [MultiPolygonTrait] type MultiPolygon<'a>: 'a + MultiPolygonTrait where Self: 'a; + + /// The type of each underlying GeometryCollection, which implements [GeometryCollectionTrait] type GeometryCollection<'a>: 'a + GeometryCollectionTrait where Self: 'a; + + /// The type of each underlying Rect, which implements [RectTrait] type Rect<'a>: 'a + RectTrait where Self: 'a; + /// The number of dimensions in this geometry fn dim(&self) -> usize; + /// Cast this geometry to a [`GeometryType`] enum, which allows for downcasting to a specific + /// type fn as_type( &self, ) -> GeometryType< @@ -68,13 +88,21 @@ where 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), } diff --git a/src/geo_traits/geometry_collection.rs b/src/geo_traits/geometry_collection.rs index ac47ef8f..916f8ac3 100644 --- a/src/geo_traits/geometry_collection.rs +++ b/src/geo_traits/geometry_collection.rs @@ -4,11 +4,15 @@ use geo::{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 where Self: 'a; + /// The number of dimensions in this geometry fn dim(&self) -> usize; /// An iterator over the geometries in this GeometryCollection diff --git a/src/geo_traits/iterator.rs b/src/geo_traits/iterator.rs index a11b8f5a..a88c76b1 100644 --- a/src/geo_traits/iterator.rs +++ b/src/geo_traits/iterator.rs @@ -25,6 +25,7 @@ macro_rules! impl_iterator { G: $self_trait = ItemType>, > $struct_name<'a, T, ItemType, G> { + /// Create a new iterator pub fn new(geom: &'a G, index: usize, end: usize) -> Self { Self { geom, index, end } } diff --git a/src/geo_traits/line_string.rs b/src/geo_traits/line_string.rs index 631e3be4..5b084cd8 100644 --- a/src/geo_traits/line_string.rs +++ b/src/geo_traits/line_string.rs @@ -4,11 +4,15 @@ use geo::{Coord, CoordNum, LineString}; /// A trait for accessing data from a generic LineString. pub trait LineStringTrait: Sized { + /// The coordinate type of this geometry type T: CoordNum; + + /// The type of each underlying coordinate, which implements [CoordTrait] type ItemType<'a>: 'a + CoordTrait where Self: 'a; + /// The number of dimensions in this geometry fn dim(&self) -> usize; /// An iterator over the coords in this LineString diff --git a/src/geo_traits/mod.rs b/src/geo_traits/mod.rs index 1c8429a6..d2105fab 100644 --- a/src/geo_traits/mod.rs +++ b/src/geo_traits/mod.rs @@ -8,8 +8,6 @@ //! [here](https://github.com/georust/geo/pull/1019)) but that is vendored into this repository for //! use internally, such as in the WKB parser. -#![allow(missing_docs)] // FIXME - pub use coord::CoordTrait; pub use geometry::{GeometryTrait, GeometryType}; pub use geometry_collection::GeometryCollectionTrait; diff --git a/src/geo_traits/multi_line_string.rs b/src/geo_traits/multi_line_string.rs index 205f8b18..ef980780 100644 --- a/src/geo_traits/multi_line_string.rs +++ b/src/geo_traits/multi_line_string.rs @@ -4,11 +4,15 @@ use geo::{CoordNum, LineString, MultiLineString}; /// A trait for accessing data from a generic MultiLineString. pub trait MultiLineStringTrait: Sized { + /// The coordinate type of this geometry type T: CoordNum; + + /// The type of each underlying LineString, which implements [LineStringTrait] type ItemType<'a>: 'a + LineStringTrait where Self: 'a; + /// The number of dimensions in this geometry fn dim(&self) -> usize; /// An iterator over the LineStrings in this MultiLineString diff --git a/src/geo_traits/multi_point.rs b/src/geo_traits/multi_point.rs index 05cad71a..b7463612 100644 --- a/src/geo_traits/multi_point.rs +++ b/src/geo_traits/multi_point.rs @@ -4,11 +4,15 @@ use geo::{CoordNum, MultiPoint, Point}; /// A trait for accessing data from a generic MultiPoint. pub trait MultiPointTrait: Sized { + /// The coordinate type of this geometry type T: CoordNum; + + /// The type of each underlying Point, which implements [PointTrait] type ItemType<'a>: 'a + PointTrait where Self: 'a; + /// The number of dimensions in this geometry fn dim(&self) -> usize; /// An iterator over the points in this MultiPoint diff --git a/src/geo_traits/multi_polygon.rs b/src/geo_traits/multi_polygon.rs index 62c76717..18923e78 100644 --- a/src/geo_traits/multi_polygon.rs +++ b/src/geo_traits/multi_polygon.rs @@ -4,11 +4,15 @@ use geo::{CoordNum, MultiPolygon, Polygon}; /// A trait for accessing data from a generic MultiPolygon. pub trait MultiPolygonTrait: Sized { + /// The coordinate type of this geometry type T: CoordNum; + + /// The type of each underlying Polygon, which implements [PolygonTrait] type ItemType<'a>: 'a + PolygonTrait where Self: 'a; + /// The number of dimensions in this geometry fn dim(&self) -> usize; /// An iterator over the Polygons in this MultiPolygon diff --git a/src/geo_traits/point.rs b/src/geo_traits/point.rs index 9745d456..76f3cae4 100644 --- a/src/geo_traits/point.rs +++ b/src/geo_traits/point.rs @@ -2,6 +2,7 @@ use geo::{Coord, CoordNum, Point}; /// A trait for accessing data from a generic Point. pub trait PointTrait { + /// The coordinate type of this geometry type T: CoordNum; /// Access the n'th (0-based) element of the CoordinateTuple. diff --git a/src/geo_traits/polygon.rs b/src/geo_traits/polygon.rs index e88abd52..450a7e4d 100644 --- a/src/geo_traits/polygon.rs +++ b/src/geo_traits/polygon.rs @@ -4,11 +4,15 @@ use geo::{CoordNum, LineString, Polygon}; /// A trait for accessing data from a generic Polygon. pub trait PolygonTrait: Sized { + /// The coordinate type of this geometry type T: CoordNum; + + /// The type of each underlying ring, which implements [LineStringTrait] type ItemType<'a>: 'a + LineStringTrait where Self: 'a; + /// The number of dimensions in this geometry fn dim(&self) -> usize; /// The exterior ring of the polygon diff --git a/src/geo_traits/rect.rs b/src/geo_traits/rect.rs index 16a35fc4..e65c9b22 100644 --- a/src/geo_traits/rect.rs +++ b/src/geo_traits/rect.rs @@ -4,15 +4,21 @@ use crate::geo_traits::CoordTrait; /// A trait for accessing data from a generic Rect. pub trait RectTrait { + /// The coordinate type of this geometry type T: CoordNum; + + /// The type of each underlying coordinate, which implements [CoordTrait] type ItemType<'a>: 'a + CoordTrait where Self: 'a; + /// The number of dimensions in this geometry fn dim(&self) -> usize; + /// The lower coordinate of this Rect fn lower(&self) -> Self::ItemType<'_>; + /// The upper coordinate of this Rect fn upper(&self) -> Self::ItemType<'_>; }