Package org.apache.sis.geometry

## Class GeneralDirectPosition

- Object
- - FormattableObject
  - - AbstractDirectPosition
    - - GeneralDirectPosition

- All Implemented Interfaces:
    `Serializable`, `Cloneable`, `Position`, `DirectPosition`

      public class GeneralDirectPosition
      extends AbstractDirectPosition
      implements Serializable, Cloneable

  A mutable `DirectPosition` (the coordinates of a position) of arbitrary dimension. This particular implementation of `DirectPosition` is said "General" because it uses an `array of coordinates` of an arbitrary length. If the direct position is known to be always two-dimensional, then `DirectPosition2D` provides a more efficient implementation.
  Coordinate Reference System (CRS) optionality
  Since `DirectPosition`s, as data types, will often be included in larger objects (such as `Geometry`) that have references to `CoordinateReferenceSystem`, the `getCoordinateReferenceSystem()` method may returns `null` if this particular `DirectPosition` is included in such larger object. In this case, the coordinate reference system is implicitly assumed to take on the value of the containing object's `CoordinateReferenceSystem`.
  Since:
    0.3
  See Also:
    `DirectPosition1D`, `DirectPosition2D`, `CoordinateFormat`, Serialized Form

  Defined in the `sis-referencing` module

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `double[]` | `coordinates` | The coordinates of the direct position.
    `double[]` | `ordinates` | Deprecated. Renamed `coordinates`.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `GeneralDirectPosition​(double... coordinates)` | Constructs a position with the specified coordinates.
    `GeneralDirectPosition​(int dimension)` | Constructs a position with the specified number of dimensions.
    `GeneralDirectPosition​(CharSequence wkt)` | Constructs a position initialized to the values parsed from the given string in Well Known Text (WKT) format.
    `GeneralDirectPosition​(DirectPosition point)` | Constructs a position initialized to the same values than the specified point.
    `GeneralDirectPosition​(CoordinateReferenceSystem crs)` | Constructs a position using the specified coordinate reference system.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `GeneralDirectPosition` | `clone()` | Returns a deep copy of this position.
    `boolean` | `equals​(Object object)` | Returns `true` if the specified object is also a `DirectPosition` with equal coordinates and equal CRS.
    `double[]` | `getCoordinate()` | Returns a sequence of numbers that hold the coordinate of this position in its reference system.
    `CoordinateReferenceSystem` | `getCoordinateReferenceSystem()` | Returns the coordinate reference system in which the coordinate is given.
    `int` | `getDimension()` | The length of coordinate sequence (the number of entries).
    `double` | `getOrdinate​(int dimension)` | Returns the coordinate at the specified dimension.
    `int` | `hashCode()` | Returns a hash value for this coordinate tuple.
    `void` | `setCoordinate​(double... coordinates)` | Sets the coordinate values along all dimensions.
    `void` | `setCoordinateReferenceSystem​(CoordinateReferenceSystem crs)` | Sets the coordinate reference system in which the coordinate is given.
    `void` | `setLocation​(DirectPosition position)` | Sets this coordinate to the specified direct position.
    `void` | `setOrdinate​(int dimension, double value)` | Sets the coordinate value along the specified dimension.
    `String` | `toString()` | Formats this position in the Well Known Text (WKT) format.

    - ### Methods inherited from class AbstractDirectPosition

      `castOrCopy, formatTo, getDirectPosition, normalize`

    - ### Methods inherited from class FormattableObject

      `print, toString, toWKT`

    - ### Methods inherited from class Object

      `finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### coordinates

          public final double[] coordinates

      The coordinates of the direct position. The length of this array is the dimension of this direct position.

    - #### ordinates

          @Deprecated
          public transient double[] ordinates

      Deprecated.
      Renamed `coordinates`.
      See Also:
        SIS-461

  - ### Constructor Detail

    - #### GeneralDirectPosition

          public GeneralDirectPosition​(CoordinateReferenceSystem crs)

      Constructs a position using the specified coordinate reference system. The number of dimensions is inferred from the coordinate reference system.
      Parameters:
        `crs` - the coordinate reference system to be given to this position.

    - #### GeneralDirectPosition

          public GeneralDirectPosition​(int dimension)
                                throws NegativeArraySizeException

      Constructs a position with the specified number of dimensions.
      Parameters:
        `dimension` - number of dimensions.
      Throws:
        `NegativeArraySizeException` - if `dimension` is negative.

    - #### GeneralDirectPosition

          public GeneralDirectPosition​(double... coordinates)

      Constructs a position with the specified coordinates. This constructor assigns the given array directly (without clone) to the `coordinates` field. Consequently, callers shall not recycle the same array for creating many instances.
      Implementation note: the array is not cloned because this is usually not needed, especially in the context of variable argument lengths since the array is often created implicitly. Furthermore the `coordinates` field is public, so cloning the array would not protect the state of this object anyway.

      Caution: if only one number is specified, make sure that the number type is `double`, `float` or `long` otherwise the `GeneralDirectPosition(int)` constructor would be invoked with a very different meaning. For example for creating a one-dimensional coordinate initialized to the coordinate value 100, use `new GeneralDirectPosition(100.0)`, not `new GeneralDirectPosition(100)`, because the later would actually create a position with 100 dimensions.

      Parameters:
        `coordinates` - the coordinate values. This array is not cloned.

    - #### GeneralDirectPosition

          public GeneralDirectPosition​(DirectPosition point)

      Constructs a position initialized to the same values than the specified point. This is a copy constructor.
      Parameters:
        `point` - the position to copy.

    - #### GeneralDirectPosition

          public GeneralDirectPosition​(CharSequence wkt)
                                throws IllegalArgumentException

      Constructs a position initialized to the values parsed from the given string in Well Known Text (WKT) format. The given string is typically a `POINT` element like below:

      >     POINT(6 10)

      However this constructor is lenient to other types like `POINT ZM`.
      Parameters:
        `wkt` - the `POINT` or other kind of element to parse.
      Throws:
        `IllegalArgumentException` - if the given string can not be parsed.
      See Also:
        `toString()`, `CoordinateFormat`

  - ### Method Detail

    - #### getDimension

          public final int getDimension()

      The length of coordinate sequence (the number of entries). This is always equals to the length of the `coordinates` array.
      Specified by:
        `getDimension` in interface `DirectPosition`
      Returns:
        the dimensionality of this position.

    - #### getCoordinateReferenceSystem

          public final CoordinateReferenceSystem getCoordinateReferenceSystem()

      Returns the coordinate reference system in which the coordinate is given. May be `null` if this particular `DirectPosition` is included in a larger object with such a reference to a CRS.
      Specified by:
        `getCoordinateReferenceSystem` in interface `DirectPosition`
      Returns:
        the coordinate reference system, or `null`.

    - #### setCoordinateReferenceSystem

          public void setCoordinateReferenceSystem​(CoordinateReferenceSystem crs)
                                            throws MismatchedDimensionException

      Sets the coordinate reference system in which the coordinate is given.
      Parameters:
        `crs` - the new coordinate reference system, or `null`.
      Throws:
        `MismatchedDimensionException` - if the specified CRS does not have the expected number of dimensions.

    - #### getCoordinate

          public final double[] getCoordinate()

      Returns a sequence of numbers that hold the coordinate of this position in its reference system.
      API note: This method is final for ensuring consistency with the `coordinates`, array field, which is public.
      Specified by:
        `getCoordinate` in interface `DirectPosition`
      Overrides:
        `getCoordinate` in class `AbstractDirectPosition`
      Returns:
        a copy of the `coordinates` array.

    - #### setCoordinate

          public void setCoordinate​(double... coordinates)
                             throws MismatchedDimensionException

      Sets the coordinate values along all dimensions.
      Parameters:
        `coordinates` - the new coordinates values, or a `null` array for setting all coordinate values to `NaN`.
      Throws:
        `MismatchedDimensionException` - if the length of the specified array is not equals to the dimension of this position.

    - #### getOrdinate

          public final double getOrdinate​(int dimension)
                                   throws IndexOutOfBoundsException

      Returns the coordinate at the specified dimension.
      API note: This method is final for ensuring consistency with the `coordinates`, array field, which is public.
      Specified by:
        `getOrdinate` in interface `DirectPosition`
      Parameters:
        `dimension` - the dimension in the range 0 to dimension-1.
      Returns:
        the coordinate at the specified dimension.
      Throws:
        `IndexOutOfBoundsException` - if the specified dimension is out of bounds.

    - #### setOrdinate

          public void setOrdinate​(int dimension,
                                  double value)
                           throws IndexOutOfBoundsException

      Sets the coordinate value along the specified dimension.
      Specified by:
        `setOrdinate` in interface `DirectPosition`
      Parameters:
        `dimension` - the dimension for the coordinate of interest.
        `value` - the coordinate value of interest.
      Throws:
        `IndexOutOfBoundsException` - if the specified dimension is out of bounds.

    - #### setLocation

          public void setLocation​(DirectPosition position)
                           throws MismatchedDimensionException

      Sets this coordinate to the specified direct position. If the specified position contains a coordinate reference system (CRS), then the CRS for this position will be set to the CRS of the specified position.
      Overrides:
        `setLocation` in class `AbstractDirectPosition`
      Parameters:
        `position` - the new position for this point, or `null` for setting all coordinate values to `NaN`.
      Throws:
        `MismatchedDimensionException` - if the given position does not have the expected dimension.

    - #### toString

          public String toString()

      Formats this position in the Well Known Text (WKT) format. The returned string is like below, where `x₀`, `x₁`, `x₂`, etc. are the coordinate values at index 0, 1, 2, etc.:

      >     POINT(x₀ x₁ x₂ …)

      This method formats the numbers as with `Double​.toString(double)` (i.e. without fixed number of fraction digits). The string returned by this method can be parsed by the `GeneralDirectPosition` constructor.
      Overrides:
        `toString` in class `AbstractDirectPosition`
      Returns:
        this position as a `POINT` in Well Known Text (WKT) format.

    - #### clone

          public GeneralDirectPosition clone()

      Returns a deep copy of this position.
      Overrides:
        `clone` in class `Object`
      Returns:
        a copy of this direct position.

    - #### hashCode

          public int hashCode()

      Returns a hash value for this coordinate tuple. This method returns a value compliant with the contract documented in the `DirectPosition​.hashCode()` javadoc. Consequently, it should be possible to mix different `DirectPosition` implementations in the same hash map.
      Specified by:
        `hashCode` in interface `DirectPosition`
      Overrides:
        `hashCode` in class `AbstractDirectPosition`
      Returns:
        a hash code value for this position.

    - #### equals

          public boolean equals​(Object object)

      Returns `true` if the specified object is also a `DirectPosition` with equal coordinates and equal CRS. This method performs the comparison as documented in the `DirectPosition​.equals(Object)` javadoc. In particular, the given object is not required to be of the same implementation class. Consequently, it should be possible to mix different `DirectPosition` implementations in the same hash map.
      Specified by:
        `equals` in interface `DirectPosition`
      Overrides:
        `equals` in class `AbstractDirectPosition`
      Parameters:
        `object` - the object to compare with this position.
      Returns:
        `true` if the given object is equal to this position.