[traits] rename CoordTrait::nth_unchecked -> nth_or_panic to match co…

…nventional semantics

`unchecked` implies it's an unsafe method, like `Vec::get_unsafe`

Also cleaned up some stale docs.

geo-traits/CHANGES.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+- BREAKING: Rename `CoordTrait::nth_unchecked` -> `CoordTrait::nth_or_panic` since it is not `unsafe`.
+  - <https://github.com/georust/geo/pull/1242>
+
 ## 0.1.1
 
 - Fix `TriangleTrait::second` and `TriangleTrait::third` to return the second and third coordinates instead of the first.

geo-traits/src/coord.rs

@@ -16,10 +16,10 @@ pub trait CoordTrait {
 
     /// Access the n'th (0-based) element of the CoordinateTuple.
     /// Returns `None` if `n >= DIMENSION`.
-    /// See also [`nth_unchecked()`](Self::nth_unchecked).
+    /// See also [`nth_or_panic()`](Self::nth_or_panic).
     fn nth(&self, n: usize) -> Option<Self::T> {
         if n < self.dim().size() {
-            Some(self.nth_unchecked(n))
+            Some(self.nth_or_panic(n))
         } else {
             None
         }
@@ -39,13 +39,13 @@ pub trait CoordTrait {
     /// Access the n'th (0-based) element of the CoordinateTuple.
     /// May panic if n >= DIMENSION.
     /// See also [`nth()`](Self::nth).
-    fn nth_unchecked(&self, n: usize) -> Self::T;
+    fn nth_or_panic(&self, n: usize) -> Self::T;
 }
 
 impl<T: CoordNum> CoordTrait for Coord<T> {
     type T = T;
 
-    fn nth_unchecked(&self, n: usize) -> Self::T {
+    fn nth_or_panic(&self, n: usize) -> Self::T {
         match n {
             0 => self.x(),
             1 => self.y(),
@@ -69,7 +69,7 @@ impl<T: CoordNum> CoordTrait for Coord<T> {
 impl<T: CoordNum> CoordTrait for &Coord<T> {
     type T = T;
 
-    fn nth_unchecked(&self, n: usize) -> Self::T {
+    fn nth_or_panic(&self, n: usize) -> Self::T {
         match n {
             0 => self.x(),
             1 => self.y(),
@@ -93,7 +93,7 @@ impl<T: CoordNum> CoordTrait for &Coord<T> {
 impl<T: CoordNum> CoordTrait for (T, T) {
     type T = T;
 
-    fn nth_unchecked(&self, n: usize) -> Self::T {
+    fn nth_or_panic(&self, n: usize) -> Self::T {
         match n {
             0 => self.x(),
             1 => self.y(),
@@ -127,7 +127,7 @@ impl<T: CoordNum> CoordTrait for UnimplementedCoord<T> {
         unimplemented!()
     }
 
-    fn nth_unchecked(&self, _n: usize) -> Self::T {
+    fn nth_or_panic(&self, _n: usize) -> Self::T {
         unimplemented!()
     }
 

geo-traits/src/point.rs

@@ -19,16 +19,9 @@ pub trait PointTrait {
     /// Dimensions of the coordinate tuple
     fn dim(&self) -> Dimensions;
 
-    /// Whether this point is `empty` or not.
+    /// The location of this 0-dimensional geometry.
     ///
-    /// According to Simple Features, a Point can have zero coordinates and be considered `empty`.
-    ///
-    /// If `is_empty` returns `true`, then the values of `x()`, `y()`, `nth()` and `nth_unchecked`
-    /// have no semantic meaning.
-    ///
-    /// Only a top-level geometry can be empty. That is, when this point is contained within
-    /// another geometry, such as a [`LineStringTrait`][crate::LineStringTrait], those points
-    /// can never be empty, and a consumer does not need to check this method.
+    /// According to Simple Features, a Point can have zero coordinates and be considered "empty".
     fn coord(&self) -> Option<Self::CoordType<'_>>;
 }