Module org.apache.sis.util
Package org.apache.sis.measure

# Class Longitude

Object
Angle
Longitude

All Implemented Interfaces:
  `Serializable`, `Comparable<Angle>`, `Formattable`

public final class Longitude extends Angle
A longitude angle in decimal degrees. Positive longitudes are East, while negative longitudes are West. The longitude symbol is the Greek lower-case letter lambda (λ).

Longitudes are not necessarily relative to the Greenwich meridian. The prime meridian depends on the context, typically specified through the geodetic datum of a geographic CRS.

## Immutability and thread safety

This final class is immutable and thus inherently thread-safe.

Since:
  0.3
See Also:
  - `Latitude`
  - `AngleFormat`
  - `CoordinateFormat`
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final double`
  `MAX_VALUE`
  Maximum usual value for longitude (+180.0°).
  `static final double`
  `MIN_VALUE`
  Minimum usual value for longitude (-180.0°).

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Longitude(double λ)`
  Construct a new longitude with the specified angular value.
  `Longitude(String string)`
  Constructs a newly allocated `Longitude` object that contain the angular value represented by the string.
  `Longitude(DirectPosition position)`
  Constructs a newly allocated object containing the longitude value of the given position.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static boolean`
  `isWraparound(double west, double east)`
  Returns `true` if the given longitude range crosses the anti-meridian in a way expressed by west > east.
  `static double`
  `normalize(double λ)`
  Returns the given longitude value normalized to the [-180.0 … 180.0)° range (upper value is exclusive).

  ### Methods inherited from class Angle

  `compareTo, degrees, equals, formatTo, hashCode, radians, toString`

  ### Methods inherited from class Object

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

- ## Field Details

  - ### MIN_VALUE

    public static final double MIN_VALUE
    Minimum usual value for longitude (-180.0°).
    See Also:
      - `DefaultCoordinateSystemAxis​.getMinimumValue()`
      - Constant Field Values

  - ### MAX_VALUE

    public static final double MAX_VALUE
    Maximum usual value for longitude (+180.0°).
    See Also:
      - `DefaultCoordinateSystemAxis​.getMaximumValue()`
      - Constant Field Values

- ## Constructor Details

  - ### Longitude

    public Longitude(double λ)
    Construct a new longitude with the specified angular value. This constructor does not normalize the given value.
    Parameters:
      `λ` - longitude value in decimal degrees.

  - ### Longitude

    public Longitude(String string) throws NumberFormatException
    Constructs a newly allocated `Longitude` object that contain the angular value represented by the string. The string should represent an angle in either fractional degrees (e.g. 45.5°) or degrees with minutes and seconds (e.g. 45°30'). The hemisphere (E or W) is optional (default to East).

    This is a convenience constructor mostly for testing purpose, since it uses a fixed locale. Developers should consider using `AngleFormat` for end-user applications instead of this constructor.

    Parameters:
      `string` - a string to be converted to a `Longitude`.
    Throws:
      `NumberFormatException` - if the string does not contain a parsable angle, or represents a longitude angle.
    See Also:
      - `AngleFormat​.parse(String)`

  - ### Longitude

    public Longitude(DirectPosition position) throws IllegalArgumentException
    Constructs a newly allocated object containing the longitude value of the given position. For this method, the longitude value is defined as the angular value associated to the first axis oriented toward East or West. Note that this is not necessarily the geodetic longitudes used in geographic CRS; it may also be geocentric longitudes.

    If the axis direction is West, then the sign of the coordinate value is inverted. If the coordinate value uses another angular units than degrees, then a unit conversion is applied.

    Parameters:
      `position` - the coordinate from which to extract the longitude value in degrees.
    Throws:
      `IllegalArgumentException` - if the given coordinate it not associated to a CRS, or if no axis oriented toward East or West is found, or if that axis does not use angular units.
    Since:
      0.8

- ## Method Details

  - ### normalize

    public static double normalize(double λ)
    Returns the given longitude value normalized to the [-180.0 … 180.0)° range (upper value is exclusive). If the given value is outside the longitude range, then this method adds or subtracts a multiple of 360° in order to bring back the value to that range.

    Special cases:

    - NaN values are returned unchanged
    - ±∞ are mapped to NaN
    - ±180° are both mapped to -180° (i.e. the range is from -180° inclusive to +180° exclusive)
    - ±0 are returned unchanged (i.e. the sign of negative and positive zero is preserved)
    Note that the given value should not be greater than 4×10⁸ degrees if a centimetric precision is desired.
    Parameters:
      `λ` - the longitude value in decimal degrees.
    Returns:
      the given value normalized to the [-180 … 180)° range, or NaN if the given value was NaN of infinite.
    Since:
      0.4
    See Also:
      - `Latitude​.clamp(double)`

  - ### isWraparound

    public static boolean isWraparound(double west, double east)
    Returns `true` if the given longitude range crosses the anti-meridian in a way expressed by west > east. For the purpose of this method, +0 is considered "greater" than −0. See `GeneralEnvelope` for a wraparound illustration.
    Parameters:
      `west` - the west bound longitude. This is the minimum value when there is no wraparound.
      `east` - the east bound longitude. This is the maximum value when there is no wraparound.
    Returns:
      `true` if west > east or if the arguments are (+0, −0), `false` otherwise (including when at least one argument is NaN).
    Since:
      1.1