Merge branch 'master' into clippy

.github/workflows/test.yml

@@ -16,8 +16,13 @@ jobs:
     container:
       image: georust/geo-ci
     steps:
+      - name: Install Rust toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          profile: minimal
+          override: true
+          components: rustfmt, rust-src
       - name: Checkout repository
         uses: actions/checkout@v2
-      - run: cargo install cargo-all-features
-      - run: cargo build-all-features
-      - run: cargo test-all-features
+      - run: cargo test --all-features && cargo test --no-default-features

CHANGES.md

@@ -8,6 +8,8 @@
   * <https://github.com/georust/wkt/pull/72>
 * BREAKING: Reject empty strings instead of parsing them into an empty `Wkt`.
   * <https://github.com/georust/wkt/pull/72>
+* Switch to 2021 edition and add examples
+  * <https://github.com/georust/wkt/pull/65>
 
 ## 0.9.2 - 2020-04-30
 ### Added

Cargo.toml

@@ -8,6 +8,7 @@ repository = "https://github.com/georust/wkt"
 autobenches = true
 readme = "README.md"
 keywords = ["geo", "geospatial", "wkt"]
+edition = "2021"
 
 [dependencies]
 geo-types = { version = "0.7.1", optional = true }

src/conversion.rs

@@ -1,3 +1,11 @@
+//! This module provides conversions between WKT primitives and [`geo_types`] primitives.
+//!
+//! See the [`std::convert::From`] and [`std::convert::TryFrom`] impls on individual [`crate::types`] and [`Wkt`] for details.
+//!
+//!
+//!
+//!
+//!
 // Copyright 2014-2018 The GeoRust Developers
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
@@ -12,16 +20,17 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-use types::*;
-use Geometry;
-use Wkt;
+use crate::types::*;
+use crate::Geometry;
+use crate::Wkt;
 
 use std::convert::{TryFrom, TryInto};
 
 use geo_types::CoordFloat;
 use thiserror::Error;
 
 #[derive(Error, Debug)]
+/// WKT to [`geo_types`] conversion errors
 pub enum Error {
     #[error("The WKT Point was empty, but geo_type::Points cannot be empty")]
     PointConversionError,
@@ -41,7 +50,7 @@ where
     T: CoordFloat,
 {
     type Error = Error;
-
+    /// Try to convert from a WKT member to a [`geo-types`] primitive or collection
     fn try_from(wkt: Wkt<T>) -> Result<Self, Self::Error> {
         Self::try_from(wkt.item)
     }
@@ -50,7 +59,7 @@ where
 macro_rules! try_from_wkt_impl {
     ($($type: ident),+) => {
         $(
-            /// Convert a Wkt enum into a specific geo-type
+            /// Fallibly convert this WKT primitive into this [`geo_types`] primitive
             impl<T: CoordFloat> TryFrom<Wkt<T>> for geo_types::$type<T> {
                 type Error = Error;
 
@@ -89,6 +98,7 @@ impl<T> From<Coord<T>> for geo_types::Coordinate<T>
 where
     T: CoordFloat,
 {
+    /// Convert from a WKT Coordinate to a [`geo_types::Coordinate`]
     fn from(coord: Coord<T>) -> geo_types::Coordinate<T> {
         Self {
             x: coord.x,
@@ -103,6 +113,7 @@ where
 {
     type Error = Error;
 
+    /// Fallibly convert from a WKT `POINT` to a [`geo_types::Point`]
     fn try_from(point: Point<T>) -> Result<Self, Self::Error> {
         match point.0 {
             Some(coord) => Ok(Self::new(coord.x, coord.y)),
@@ -132,6 +143,7 @@ impl<T> From<LineString<T>> for geo_types::LineString<T>
 where
     T: CoordFloat,
 {
+    /// Convert from a WKT `LINESTRING` to a [`geo_types::LineString`]
     fn from(line_string: LineString<T>) -> Self {
         let coords = line_string
             .0
@@ -156,6 +168,7 @@ impl<T> From<MultiLineString<T>> for geo_types::MultiLineString<T>
 where
     T: CoordFloat,
 {
+    /// Convert from a WKT `MULTILINESTRING` to a [`geo_types::MultiLineString`]
     fn from(multi_line_string: MultiLineString<T>) -> geo_types::MultiLineString<T> {
         let geo_line_strings: Vec<geo_types::LineString<T>> = multi_line_string
             .0
@@ -180,6 +193,7 @@ impl<T> From<Polygon<T>> for geo_types::Polygon<T>
 where
     T: CoordFloat,
 {
+    /// Convert from a WKT `POLYGON` to a [`geo_types::Polygon`]
     fn from(polygon: Polygon<T>) -> Self {
         let mut iter = polygon.0.into_iter().map(geo_types::LineString::from);
         match iter.next() {
@@ -205,7 +219,7 @@ where
     T: CoordFloat,
 {
     type Error = Error;
-
+    /// Fallibly convert from a WKT `MULTIPOINT` to a [`geo_types::MultiPoint`]
     fn try_from(multi_point: MultiPoint<T>) -> Result<Self, Self::Error> {
         let points: Vec<geo_types::Point<T>> = multi_point
             .0
@@ -230,6 +244,7 @@ impl<T> From<MultiPolygon<T>> for geo_types::MultiPolygon<T>
 where
     T: CoordFloat,
 {
+    /// Convert from a WKT `MULTIPOLYGON` to a [`geo_types::MultiPolygon`]
     fn from(multi_polygon: MultiPolygon<T>) -> Self {
         let geo_polygons: Vec<geo_types::Polygon<T>> = multi_polygon
             .0

src/deserialize.rs

@@ -1,3 +1,5 @@
+//! This module provides deserialisation to WKT primitives using [`serde`]
+
 use crate::{Geometry, Wkt, WktFloat};
 use serde::de::{Deserializer, Error, Visitor};
 use std::{
@@ -88,7 +90,7 @@ where
     }
 }
 
-/// Deserializes directly from WKT format into a geo_types::Geometry.
+/// Deserializes directly from WKT format into a [`geo_types::Geometry`].
 /// ```
 /// # extern crate wkt;
 /// # extern crate geo_types;
@@ -118,7 +120,7 @@ where
     })
 }
 
-/// Deserializes directly from WKT format into a `Option<geo_types::Point>`.
+/// Deserializes directly from WKT format into an `Option<geo_types::Point>`.
 ///
 /// # Examples
 ///
@@ -153,7 +155,6 @@ where
 {
     use serde::Deserialize;
     Wkt::deserialize(deserializer).and_then(|wkt: Wkt<T>| {
-        use std::convert::TryFrom;
         geo_types::Geometry::try_from(wkt)
             .map_err(D::Error::custom)
             .and_then(|geom| {

src/lib.rs

@@ -1,3 +1,4 @@
+#![doc(html_logo_url = "https://raw.githubusercontent.com/georust/meta/master/logo/logo.png")]
 // Copyright 2014-2015 The GeoRust Developers
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
@@ -12,24 +13,68 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! The `wkt` crate provides conversions to and from [`WKT`](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) primitive types.
+//! See the [`types`](crate::types) module for a list of available types.
+//!
+//! Conversions (using [`std::convert::From`] and [`std::convert::TryFrom`]) to and from [`geo_types`] primitives are enabled by default, but the feature is **optional**.
+//!
+//! Enable the `serde` feature if you need to deserialise data into custom structs containing `WKT` geometry fields.
+//!
+//! # Examples
+//!
+//! ```
+//! use wkt::Wkt;
+//! let point: Wkt<f64> = Wkt::from_str("POINT(10 20)").unwrap();
+//! ```
+//!
+//! ```ignore
+//! // Convert to a geo_types primitive from a Wkt struct
+//! use std::convert::TryInto;
+//! use wkt::Wkt;
+//! use geo_types::Point;
+//! let point: Wkt<f64> = Wkt::from_str("POINT(10 20)").unwrap();
+//! let g_point: geo_types::Point<f64> = (10., 20.).into();
+// // We can attempt to directly convert the Wkt without having to access its items field
+//! let converted: Point<f64> = point.try_into().unwrap();
+//! assert_eq!(g_point, converted);
+//! ```
+//!
+//! ## Direct Access to the `item` Field
+//! If you wish to work directly with one of the WKT [`types`] you can match on the `item` field
+//! ```
+//! use std::convert::TryInto;
+//! use wkt::Wkt;
+//! use wkt::Geometry;
+//!
+//! let wktls: Wkt<f64> = Wkt::from_str("LINESTRING(10 20, 20 30)").unwrap();
+//! let ls = match wktls.item {
+//!     Geometry::LineString(line_string) => {
+//!         // you now have access to the types::LineString
+//!     }
+//!     _ => unreachable!(),
+//! };
+//!
+//!
+//!
 use std::default::Default;
 use std::fmt;
 use std::str::FromStr;
 
-use tokenizer::{PeekableTokens, Token, Tokens};
-use types::GeometryCollection;
-use types::LineString;
-use types::MultiLineString;
-use types::MultiPoint;
-use types::MultiPolygon;
-use types::Point;
-use types::Polygon;
+use crate::tokenizer::{PeekableTokens, Token, Tokens};
+use crate::types::GeometryCollection;
+use crate::types::LineString;
+use crate::types::MultiLineString;
+use crate::types::MultiPoint;
+use crate::types::MultiPolygon;
+use crate::types::Point;
+use crate::types::Polygon;
 
 mod tokenizer;
 
 #[cfg(feature = "geo-types")]
 mod towkt;
 
+/// `WKT` primitive types and collections
 pub mod types;
 
 #[cfg(feature = "geo-types")]
@@ -38,7 +83,7 @@ extern crate geo_types;
 extern crate thiserror;
 
 #[cfg(feature = "geo-types")]
-pub use towkt::ToWkt;
+pub use crate::towkt::ToWkt;
 
 #[cfg(feature = "geo-types")]
 pub mod conversion;
@@ -54,6 +99,7 @@ pub trait WktFloat: num_traits::Float + std::fmt::Debug {}
 impl<T> WktFloat for T where T: num_traits::Float + std::fmt::Debug {}
 
 #[derive(Clone, Debug)]
+/// All supported WKT geometry [`types`]
 pub enum Geometry<T>
 where
     T: WktFloat,
@@ -127,6 +173,9 @@ where
 }
 
 #[derive(Clone, Debug)]
+/// Container for WKT primitives and collections
+///
+/// This type can be fallibly converted to a [`geo_types`] primitive using [`std::convert::TryFrom`].
 pub struct Wkt<T>
 where
     T: WktFloat,
@@ -214,8 +263,8 @@ where
 
 #[cfg(test)]
 mod tests {
-    use types::{Coord, MultiPolygon, Point};
-    use {Geometry, Wkt};
+    use crate::types::{Coord, MultiPolygon, Point};
+    use crate::{Geometry, Wkt};
 
     #[test]
     fn empty_string() {

src/tokenizer.rs

@@ -15,7 +15,7 @@
 use std::iter::Peekable;
 use std::marker::PhantomData;
 use std::str;
-use WktFloat;
+use crate::WktFloat;
 
 #[derive(Debug, PartialEq)]
 pub enum Token<T>

src/towkt.rs

@@ -1,9 +1,9 @@
-use types::{
+use crate::types::{
     Coord, GeometryCollection, LineString, MultiLineString, MultiPoint, MultiPolygon, Point,
     Polygon,
 };
-use Geometry;
-use Wkt;
+use crate::Geometry;
+use crate::Wkt;
 
 use geo_types::CoordFloat;
 

src/types/coord.rs

@@ -14,8 +14,8 @@
 
 use std::fmt;
 use std::str::FromStr;
-use tokenizer::{PeekableTokens, Token};
-use {FromTokens, WktFloat};
+use crate::tokenizer::{PeekableTokens, Token};
+use crate::{FromTokens, WktFloat};
 
 #[derive(Clone, Debug, Default)]
 pub struct Coord<T>

src/types/geometrycollection.rs

@@ -14,8 +14,8 @@
 
 use std::fmt;
 use std::str::FromStr;
-use tokenizer::{PeekableTokens, Token};
-use {FromTokens, Geometry, WktFloat};
+use crate::tokenizer::{PeekableTokens, Token};
+use crate::{FromTokens, Geometry, WktFloat};
 
 #[derive(Clone, Debug, Default)]
 pub struct GeometryCollection<T: WktFloat>(pub Vec<Geometry<T>>);
@@ -83,8 +83,8 @@ where
 #[cfg(test)]
 mod tests {
     use super::GeometryCollection;
-    use types::*;
-    use {Geometry, Wkt};
+    use crate::types::*;
+    use crate::{Geometry, Wkt};
 
     #[test]
     fn basic_geometrycollection() {

src/types/linestring.rs

@@ -14,9 +14,9 @@
 
 use std::fmt;
 use std::str::FromStr;
-use tokenizer::PeekableTokens;
-use types::coord::Coord;
-use {FromTokens, Geometry, WktFloat};
+use crate::tokenizer::PeekableTokens;
+use crate::types::coord::Coord;
+use crate::{FromTokens, Geometry, WktFloat};
 
 #[derive(Clone, Debug, Default)]
 pub struct LineString<T: WktFloat>(pub Vec<Coord<T>>);
@@ -63,7 +63,7 @@ where
 #[cfg(test)]
 mod tests {
     use super::{Coord, LineString};
-    use {Geometry, Wkt};
+    use crate::{Geometry, Wkt};
 
     #[test]
     fn basic_linestring() {

src/types/multilinestring.rs

@@ -14,9 +14,9 @@
 
 use std::fmt;
 use std::str::FromStr;
-use tokenizer::PeekableTokens;
-use types::linestring::LineString;
-use {FromTokens, Geometry, WktFloat};
+use crate::tokenizer::PeekableTokens;
+use crate::types::linestring::LineString;
+use crate::{FromTokens, Geometry, WktFloat};
 
 #[derive(Clone, Debug, Default)]
 pub struct MultiLineString<T: WktFloat>(pub Vec<LineString<T>>);
@@ -71,8 +71,8 @@ where
 #[cfg(test)]
 mod tests {
     use super::{LineString, MultiLineString};
-    use types::Coord;
-    use {Geometry, Wkt};
+    use crate::types::Coord;
+    use crate::{Geometry, Wkt};
 
     #[test]
     fn basic_multilinestring() {