refactor(geobase): deprecate PositionArray, PositionCoords and BoxCoo…

…rds and related extensions #201

dart/geobase/CHANGELOG.md

@@ -14,12 +14,14 @@ NOTE: Version 0.6.0 currently [under development](https://github.com/navibyte/ge
 * [Simplify Feature and FeatureCollection types #195](https://github.com/navibyte/geospatial/issues/195)
 * [Remove deprecated types in geobase version 0.6.0 #194](https://github.com/navibyte/geospatial/issues/194)
 * [Consistent crs and trs references in meta classes #196](https://github.com/navibyte/geospatial/issues/196)
+* [Deprecate PositionArray, PositionCoords and BoxCoords #201](https://github.com/navibyte/geospatial/issues/201)
 
 🛠 Refactoring:
 * isEmptyByGeometry on Bounded (and feature objects too, not only geometries)
 
 🛠 Maintenance:
-* PositionArray, PositionCoords and BoxCoords moved from vector_data to vector.
+* PositionArray, PositionCoords and BoxCoords moved from vector_data to vector
+  (and later deprecated by #201).
 
 ## 0.5.1
 

dart/geobase/lib/src/coordinates/data/position_data.dart

@@ -12,6 +12,7 @@ import '/src/utils/tolerance.dart';
 /// A fixed-length and random-access view to positions with coordinate values.
 ///
 /// See [Position] for description about supported coordinate values.
+@Deprecated('Use PositionSeries instead')
 mixin PositionData<E extends Position> implements Positionable {
   /// The number of positions in this view.
   int get length;

dart/geobase/lib/src/vector/array/box_coords.dart

@@ -4,6 +4,8 @@
 //
 // Docs: https://github.com/navibyte/geospatial
 
+// ignore_for_file: deprecated_member_use_from_same_package
+
 part of 'coordinates.dart';
 
 /// A geospatial bounding box as an iterable collection of coordinate values.
@@ -16,6 +18,7 @@ part of 'coordinates.dart';
 /// * `asGeographic`: returned as a `Geographic` bounding box
 ///
 /// See [Box] for description about supported coordinate values.
+@Deprecated('Use Box instead')
 abstract class BoxCoords extends Box with _CoordinatesMixin {
   @override
   final Iterable<double> _data;
@@ -24,6 +27,7 @@ abstract class BoxCoords extends Box with _CoordinatesMixin {
   final Coords _type;
 
   /// A bounding box with coordinate values of [type] from [source].
+  @Deprecated('Use Box.view instead')
   const BoxCoords(Iterable<double> source, {Coords type = Coords.xy})
       : _data = source,
         _type = type;
@@ -51,6 +55,7 @@ abstract class BoxCoords extends Box with _CoordinatesMixin {
   /// xyz  | west, south, minElev, east, north, maxElev
   /// xym  | west, south, minM, east, north, maxM
   /// xyzm | west, south, minElev, minM, east, north, maxElev, maxM
+  @Deprecated('Use Box.view instead')
   factory BoxCoords.view(Iterable<double> source, {Coords type = Coords.xy}) {
     if (source.length != 2 * type.coordinateDimension) {
       throw invalidCoordinates;
@@ -61,6 +66,7 @@ abstract class BoxCoords extends Box with _CoordinatesMixin {
   /// A bounding box as an iterable collection of coordinate values.
   ///
   /// This factory is compatible with `CreateBox` function type.
+  @Deprecated('Use Box.create instead')
   factory BoxCoords.create({
     required double minX,
     required double minY,
@@ -98,6 +104,7 @@ abstract class BoxCoords extends Box with _CoordinatesMixin {
   /// A minimum bounding box calculated from [positions].
   ///
   /// Throws FormatException if cannot create (ie. [positions] is empty).
+  @Deprecated('Use Box.from instead')
   factory BoxCoords.from(Iterable<Position> positions) =>
       Box.createBoxFrom(positions, BoxCoords.create);
 
@@ -109,6 +116,7 @@ abstract class BoxCoords extends Box with _CoordinatesMixin {
   /// coordinate [type].
   ///
   /// Throws FormatException if coordinates are invalid.
+  @Deprecated('Use Box.parse instead')
   factory BoxCoords.parse(
     String text, {
     Pattern? delimiter = ',',

dart/geobase/lib/src/vector/array/coordinates.dart

@@ -31,4 +31,5 @@ part 'position_coords.dart';
 /// * [PositionArray]: coordinate values of 0 to N positions in a flat structure
 /// * [PositionCoords]: coordinate values of a single position
 /// * [BoxCoords]: coordinate values of a single bounding box
+@Deprecated('Use Position, PositionSeries or Box instead')
 abstract class Coordinates extends Iterable<double> implements Positionable {}

dart/geobase/lib/src/vector/array/coordinates_extensions.dart

@@ -24,6 +24,7 @@ List<double> _requireLen(List<double> list, int len) {
 /// A helper extension on `List<double>` to handle coordinate values.
 ///
 /// See [Coordinates] for more information.
+@Deprecated('Deprecated as Coordinates is deprecated')
 extension ListCoordinateExtension on List<double> {
   /// A bounding box with coordinate values as a view backed by `this`.
   ///
@@ -103,6 +104,7 @@ extension ListCoordinateExtension on List<double> {
 
 /// A helper extension on `Iterable<Position>` to convert data as
 /// [PositionArray].
+@Deprecated('Deprecated as PositionArray is deprecated')
 extension PositionIterableCoordinatesExtension on Iterable<Position> {
   /// Returns positions of this `Position` iterable as `PositionArray`
   /// structuring coordinates a flat structure of `double` iterable.
@@ -133,6 +135,7 @@ extension PositionIterableCoordinatesExtension on Iterable<Position> {
 
 /// A helper extension on [Position] to convert position objects between
 /// subtypes like [Projected], [Geographic] and [PositionCoords].
+@Deprecated('Deprecated as PositionCoords is deprecated')
 extension PositionCoordinatesExtension on Position {
   /// Returns this position as an instance of [PositionCoords].
   ///
@@ -170,6 +173,7 @@ extension PositionCoordinatesExtension on Position {
 
 /// A helper extension on [Box] to convert position objects between
 /// subtypes like [ProjBox], [GeoBox] and [BoxCoords].
+@Deprecated('Deprecated as BoxCoords is deprecated')
 extension BoxCoordinatesExtension on Box {
   /// Returns this bounding box as an instance of [BoxCoords].
   ///

dart/geobase/lib/src/vector/array/coordinates_mixin.dart

@@ -6,6 +6,7 @@
 
 part of 'coordinates.dart';
 
+@Deprecated('Deprecated as Coordinates is too')
 mixin _CoordinatesMixin implements Coordinates {
   Iterable<double> get _data;
   Coords get _type;

dart/geobase/lib/src/vector/array/position_array.dart

@@ -4,6 +4,8 @@
 //
 // Docs: https://github.com/navibyte/geospatial
 
+// ignore_for_file: deprecated_member_use_from_same_package
+
 part of 'coordinates.dart';
 
 /// Coordinate values of geospatial positions as an iterable collection.
@@ -15,6 +17,7 @@ part of 'coordinates.dart';
 /// also use [dataTo] to map coordinate values to custom position types.
 ///
 /// See [Position] for description about supported coordinate values.
+@Deprecated('Use PositionSeries instead')
 abstract class PositionArray with _CoordinatesMixin {
   @override
   final Iterable<double> _data;
@@ -23,6 +26,7 @@ abstract class PositionArray with _CoordinatesMixin {
   final Coords _type;
 
   /// Positions with coordinate values of [type] from [source].
+  @Deprecated('Use PositionSeries.view instead')
   const PositionArray(Iterable<double> source, {Coords type = Coords.xy})
       : _data = source,
         _type = type;
@@ -47,6 +51,7 @@ abstract class PositionArray with _CoordinatesMixin {
   /// performance.
   ///
   /// See [Position] for description about supported coordinate values.
+  @Deprecated('Use PositionSeries.view instead')
   factory PositionArray.view(Iterable<double> source, {Coords type}) =
       _PositionArrayImpl.view;
 
@@ -55,6 +60,7 @@ abstract class PositionArray with _CoordinatesMixin {
   /// Coordinate values in [text] are separated by [delimiter].
   ///
   /// Throws FormatException if coordinates are invalid.
+  @Deprecated('Use PositionSeries.parse instead')
   factory PositionArray.parse(
     String text, {
     Pattern? delimiter = ',',

dart/geobase/lib/src/vector/array/position_coords.dart

@@ -4,6 +4,8 @@
 //
 // Docs: https://github.com/navibyte/geospatial
 
+// ignore_for_file: deprecated_member_use_from_same_package
+
 part of 'coordinates.dart';
 
 /// A position as an iterable collection of coordinate values.
@@ -36,6 +38,7 @@ part of 'coordinates.dart';
 /// `.xyz`  | 3D    | 3      | `double` |    +    |    +    |    +     |
 /// `.xym`  | 2D    | 3      | `double` |    +    |    +    |          | +
 /// `.xyzm` | 3D    | 4      | `double` |    +    |    +    |    +     | +
+@Deprecated('Use Position instead')
 abstract class PositionCoords extends Position with _CoordinatesMixin {
   @override
   final Iterable<double> _data;
@@ -44,6 +47,7 @@ abstract class PositionCoords extends Position with _CoordinatesMixin {
   final Coords _type;
 
   /// A geospatial position with coordinate values of [type] from [source].
+  @Deprecated('Use Position.view instead')
   const PositionCoords(Iterable<double> source, {Coords type = Coords.xy})
       : _data = source,
         _type = type;
@@ -71,13 +75,15 @@ abstract class PositionCoords extends Position with _CoordinatesMixin {
   /// xyz  | lon, lat, elev
   /// xym  | lon, lat, m
   /// xyzm | lon, lat, elev, m
+  @Deprecated('Use Position.view instead')
   factory PositionCoords.view(Iterable<double> source, {Coords type}) =
       _PositionCoordsImpl.view;
 
   /// A position as an iterable collection of [x], [y], and optional
   /// [z] and [m] values.
   ///
   /// This factory is compatible with `CreatePosition` function type.
+  @Deprecated('Use Position.create instead')
   factory PositionCoords.create({
     required double x,
     required double y,
@@ -103,6 +109,7 @@ abstract class PositionCoords extends Position with _CoordinatesMixin {
   /// provided and [text] has 3 items, then xyz coordinates are assumed.
   ///
   /// Throws FormatException if coordinates are invalid.
+  @Deprecated('Use Position.parse instead')
   factory PositionCoords.parse(
     String text, {
     Pattern? delimiter = ',',