Package org.apache.sis.measure

## Class Angle

- Object
- - Angle

- All Implemented Interfaces:
    `Serializable`, `Comparable<Angle>`, `Formattable`
  Direct Known Subclasses:
    `ElevationAngle`, `Latitude`, `Longitude`

      public class Angle
      extends Object
      implements Comparable<Angle>, Formattable, Serializable

  An angle in decimal degrees. An angle is the amount of rotation needed to bring one line or plane into coincidence with another. Various kind of angles are used in geographic information systems, some of them having a specialized class in Apache SIS:
  - Latitude is an angle ranging from 0° at the equator to 90° at the poles.
  - Longitude is an angle measured east-west from a prime meridian (usually Greenwich, but not necessarily).
  - Azimuth is a direction given by an angle between 0° and 360° measured clockwise from North.
  - Bearing is a direction given by an angle between 0° and 90° in a quadrant defined by a cardinal direction.
  - Bearing is also sometime used in navigation for an angle relative to the vessel forward direction.
  - Deflection angle is the angle between a line and the prolongation of a preceding line.
  - Interior angle is an angle measured between two lines of sight.
  - Elevation angle is the angular height from the horizontal plane to an object above the horizon.
  Formatting angles
  The recommended way to format angles is to instantiate an `AngleFormat` once, then to reuse it many times. As a convenience, `Angle` objects can also be formatted by the `"%s"` conversion specifier of `Formatter`, but this is less efficient for this class.
  Immutability and thread safety
  This class and the `Latitude` / `Longitude` subclasses are immutable, and thus inherently thread-safe. Other subclasses may or may not be immutable, at implementation choice (see `Number` for an example of a similar in purpose class having mutable subclasses).
  Since:
    0.3
  See Also:
    `Latitude`, `Longitude`, `AngleFormat`, Serialized Form

  Defined in the `sis-utility` module

- - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `Angle​(double θ)` | Constructs a new angle with the specified value in decimal degrees.
    `Angle​(String text)` | Constructs a newly allocated `Angle` object that contain the angular value represented by the string.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `int` | `compareTo​(Angle that)` | Compares two `Angle` objects numerically.
    `double` | `degrees()` | Returns the angle value in decimal degrees.
    `boolean` | `equals​(Object object)` | Compares the specified object with this angle for equality.
    `void` | `formatTo​(Formatter formatter, int flags, int width, int precision)` | Formats this angle using the provider formatter.
    `int` | `hashCode()` | Returns a hash code for this `Angle` object.
    `double` | `radians()` | Returns the angle value in radians.
    `String` | `toString()` | Returns a string representation of this `Angle` object.

    - ### Methods inherited from class Object

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

- - ### Constructor Detail

    - #### Angle

          public Angle​(double θ)

      Constructs a new angle with the specified value in decimal degrees.
      Parameters:
        `\u03b8` - angle in decimal degrees.

    - #### Angle

          public Angle​(String text)
                throws NumberFormatException

      Constructs a newly allocated `Angle` 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').

      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 than this constructor.

      Parameters:
        `text` - a string to be converted to an `Angle`.
      Throws:
        `NumberFormatException` - if the string does not contain a parsable angle.
      See Also:
        `AngleFormat​.parse(String)`

  - ### Method Detail

    - #### degrees

          public double degrees()

      Returns the angle value in decimal degrees.
      Returns:
        the angle value in decimal degrees.

    - #### radians

          public double radians()

      Returns the angle value in radians.
      Returns:
        the angle value in radians.

    - #### hashCode

          public int hashCode()

      Returns a hash code for this `Angle` object.
      Overrides:
        `hashCode` in class `Object`

    - #### equals

          public boolean equals​(Object object)

      Compares the specified object with this angle for equality.
      Overrides:
        `equals` in class `Object`
      Parameters:
        `object` - the object to compare with this angle for equality.
      Returns:
        `true` if the given object is equal to this angle.

    - #### compareTo

          public int compareTo​(Angle that)

      Compares two `Angle` objects numerically. The comparison is done as if by the `Double​.compare(double, double)` method.
      Specified by:
        `compareTo` in interface `Comparable<Angle>`
      Parameters:
        `that` - the angle to compare with this object for order.
      Returns:
        -1 if this angle is smaller than the given one, +1 if greater or 0 if equals.

    - #### toString

          public String toString()

      Returns a string representation of this `Angle` object. This is a convenience method mostly for debugging purpose, since it uses a fixed locale. Developers should consider using `AngleFormat` for end-user applications instead than this method.
      Overrides:
        `toString` in class `Object`
      See Also:
        `AngleFormat​.format(double)`

    - #### formatTo

          public void formatTo​(Formatter formatter,
                               int flags,
                               int width,
                               int precision)

      Formats this angle using the provider formatter. This method is invoked when an `Angle` object is formatted using the `"%s"` conversion specifier of `Formatter`. Users don't need to invoke this method explicitly.

      Special cases:

      - If the precision is 0, then this method formats an empty string.
      - If the precision is 1 and this angle is a `Latitude` or `Longitude`, then this method formats only the hemisphere symbol.
      - Otherwise the precision, if positive, is given to `AngleFormat​.setMaximumWidth(int)`.
      Specified by:
        `formatTo` in interface `Formattable`
      Parameters:
        `formatter` - the formatter in which to format this angle.
        `flags` - `FormattableFlags​.LEFT_JUSTIFY` for left alignment, or 0 for right alignment.
        `width` - minimal number of characters to write, padding with `' '` if necessary.
        `precision` - maximal number of characters to write, or -1 if no limit.