# Class GeneralDirectPosition

Object
FormattableObject
AbstractDirectPosition
GeneralDirectPosition

All Implemented Interfaces:
  `Serializable, Cloneable, Printable, 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

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `final double[]`
  `coordinates`
  The coordinates of the direct position.

- ## 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 as the specified point.
  `GeneralDirectPosition(CoordinateReferenceSystem crs)`
  Constructs a position using the specified coordinate reference system.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `GeneralDirectPosition`
  `clone()`
  Returns a deep copy of this position.
  `final double`
  `getCoordinate(int dimension)`
  Returns the coordinate at the specified dimension.
  `final CoordinateReferenceSystem`
  `getCoordinateReferenceSystem()`
  Returns the coordinate reference system in which the coordinates are given.
  `final double[]`
  `getCoordinates()`
  Returns a sequence of numbers that hold the coordinates of this position in its reference system.
  `final int`
  `getDimension()`
  The length of coordinate sequence (the number of entries).
  `void`
  `setCoordinate(int dimension, double value)`
  Sets the coordinate value along the specified dimension.
  `void`
  `setCoordinateReferenceSystem(CoordinateReferenceSystem crs)`
  Sets the coordinate reference system in which the coordinates are given.
  `void`
  `setCoordinates(double... coordinates)`
  Sets the coordinate values in all dimensions.
  `void`
  `setLocation(DirectPosition position)`
  Sets this coordinate to the specified direct position.

  ### Methods inherited from class AbstractDirectPosition

  `castOrCopy, formatTo, getCoordinate, getDirectPosition, getOrdinate, normalize, setOrdinate`

  ### Methods inherited from class FormattableObject

  `print, toString, toWKT`

  ### Methods inherited from class Object

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

- ## Field Details

  - ### coordinates

    public final double[] coordinates
    The coordinates of the direct position. The length of this array is the dimension of this direct position.

- ## Constructor Details

  - ### 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. All coordinate values are initialized to zero.
    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. All coordinate values are initialized to zero.
    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 notes

    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 latter 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 as 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 cannot be parsed.
    See Also:
      - `toString()`
      - `CoordinateFormat`

- ## Method Details

  - ### 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 coordinates are 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`
    Overrides:
      `getCoordinateReferenceSystem` in class `AbstractDirectPosition`
    Returns:
      the coordinate reference system, or `null`.

  - ### setCoordinateReferenceSystem

    public void setCoordinateReferenceSystem(CoordinateReferenceSystem crs) throws MismatchedDimensionException
    Sets the coordinate reference system in which the coordinates are given.
    Parameters:
      `crs` - the new coordinate reference system, or `null`.
    Throws:
      `MismatchedDimensionException` - if the specified CRS does not have the expected number of dimensions.

  - ### getCoordinates

    public final double[] getCoordinates()
    Returns a sequence of numbers that hold the coordinates of this position in its reference system.
    API note: This method is final for ensuring consistency with the `coordinates`, array field, which is public.
    Overrides:
      `getCoordinates` in class `AbstractDirectPosition`
    Returns:
      a copy of the `coordinates` array.
    Since:
      1.5

  - ### setCoordinates

    public void setCoordinates(double... coordinates) throws MismatchedDimensionException
    Sets the coordinate values in 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.
    Since:
      1.5

  - ### getCoordinate

    public final double getCoordinate(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:
      `getCoordinate` in class `AbstractDirectPosition`
    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.
    Since:
      1.5

  - ### setCoordinate

    public void setCoordinate(int dimension, double value) throws IndexOutOfBoundsException
    Sets the coordinate value along the specified dimension.
    Overrides:
      `setCoordinate` in class `AbstractDirectPosition`
    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.
    Since:
      1.5

  - ### 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.

  - ### clone

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