net.degreedays.geo
Class LongLat

java.lang.Object
  extended by net.degreedays.geo.LongLat
All Implemented Interfaces:
java.io.Serializable

public final class LongLat
extends java.lang.Object
implements java.io.Serializable

Defines a geographic position in terms of its longitude and latitude coordinates.

Also provides useful methods for measuring distances between points and moving points North, South, East, and West.

Instances of this class are immutable. You can safely reuse them and call them from multiple threads at once.


Constructor Summary
LongLat(double longitude, double latitude)
          Constructs a LongLat object with the specified longitude and latitude (take care not to mix these up).
 
Method Summary
 Distance distanceTo(LongLat longLat)
          Returns a Distance object that represents the shortest distance along the surface of the Earth from this to the specified longLat.
 LongLat east(Distance distance)
          Returns a LongLat object that represents a position the specified distance East of this.
 boolean equals(java.lang.Object o)
          Returns true if o is a LongLat object with the same longitude() and latitude() values as this.
 int hashCode()
          Overridden to ensure consistency with equals.
 double latitude()
          Returns the latitude: a number between -90 and 90 (both inclusive) representing the South/North coordinate.
 double longitude()
          Returns the longitude: a number between -180 and 180 (both inclusive) representing the West/East coordinate, zeroed on a line passing to the rear of the Royal Observatory, Greenwich (near London in the UK).
 LongLat north(Distance distance)
          Returns a LongLat object that represents a position the specified distance North of this.
 LongLat south(Distance distance)
          Returns a LongLat object that represents a position the specified distance South of this.
 java.lang.String toString()
          Returns a non-null, non-empty string representation of this object for logging and debugging purposes.
 LongLat west(Distance distance)
          Returns a LongLat object that represents a position the specified distance West of this.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

LongLat

public LongLat(double longitude,
               double latitude)
Constructs a LongLat object with the specified longitude and latitude (take care not to mix these up).

Much longitude/latitude confusion comes from the fact that people (even geographers) commonly speak of "latitude and longitude", though the co-ordinates are usually expressed in longitude-latitude order (which follows the usual convention of describing x before y in coordinate systems).

Parameters:
longitude - a double between -180 and 180 (both inclusive) representing the West/East coordinate. A zero longitude value represents a line passing to the rear of the Royal Observatory, Greenwich (near London in the UK). Negative values are to the West of that line (e.g. locations in the US all have negative longitude values), and positive values are to the East of that line.
latitude - a double between -90 and 90 (both inclusive) representing the South/North coordinate. -90 represents the South Pole, 90 represents the North Pole, and 0 represents the equator.
Throws:
java.lang.IllegalArgumentException - if either the longitude or latitude value is NaN or outside of its allowed range.
Method Detail

longitude

public double longitude()
Returns the longitude: a number between -180 and 180 (both inclusive) representing the West/East coordinate, zeroed on a line passing to the rear of the Royal Observatory, Greenwich (near London in the UK). Negative values are to the West of that line (e.g. locations in the US all have negative longitude values); positive values are to the East of that line.


latitude

public double latitude()
Returns the latitude: a number between -90 and 90 (both inclusive) representing the South/North coordinate. -90 represents the South Pole, 90 represents the North Pole, and 0 represents the equator.


distanceTo

public Distance distanceTo(LongLat longLat)
Returns a Distance object that represents the shortest distance along the surface of the Earth from this to the specified longLat.

The returned distance will be measured in metres, but it's easy to convert it into other units. For example:

 Distance londonToNewYorkInMiles = london.distanceTo(newYork).inMiles();
 

In practical terms, a.distanceTo(b) will be equal to b.distanceTo(a), but the values often won't be exactly equal because of small inaccuracies in the floating-point arithmetic that this method uses to calculate the distance between positions.

Parameters:
longLat - the geographic position to which the distance from this should be measured.
Throws:
java.lang.NullPointerException - if longLat is null.

north

public LongLat north(Distance distance)
Returns a LongLat object that represents a position the specified distance North of this.

If distance is negative, the returned LongLat will represent a position South of this.

Movements North and South are capped by the poles. At the North Pole, there is no way to go further North. So, for example, if position a is 20 miles from the North Pole, calling a.north(Distance.miles(30)) will return the position of the North Pole. It won't overshoot and start going South.

Parameters:
distance - a distance indicating how far North of this the returned LongLat position should be. (Or how far South if distance is negative.)
Throws:
java.lang.NullPointerException - if distance is null.

south

public LongLat south(Distance distance)
Returns a LongLat object that represents a position the specified distance South of this.

If distance is negative, the returned LongLat will represent a position North of this.

Movements North and South are capped by the poles. At the South Pole, there is no way to go further South. So, for example, if position a is 50 kilometres from the South Pole, calling a.south(Distance.kilometres(200)) will return the position of the South Pole. It won't overshoot and start going North.

Parameters:
distance - a distance indicating how far South of this the returned LongLat position should be. (Or how far North if distance is negative.)
Throws:
java.lang.NullPointerException - if distance is null.

east

public LongLat east(Distance distance)
Returns a LongLat object that represents a position the specified distance East of this.

If distance is negative, the returned LongLat will represent a position West of this.

Unlike movements North and South, movements East and West are not capped. In theory one can travel around the earth an infinite number of times, going only in an easterly direction. However, movements East and West are essentially meaningless at the two poles since the latitude is fixed at +90 or -90, which fixes the position to the pole itself.

Parameters:
distance - a distance indicating how far East of this the returned LongLat position should be. (Or how far West if distance is negative.)
Throws:
java.lang.NullPointerException - if distance is null.

west

public LongLat west(Distance distance)
Returns a LongLat object that represents a position the specified distance West of this.

If distance is negative, the returned LongLat will represent a position East of this.

Unlike movements North and South, movements East and West are not capped. In theory one can travel around the earth an infinite number of times, going only in an westerly direction. However, movements East and West are essentially meaningless at the two poles since the latitude is fixed at +90 or -90, which fixes the position to the pole itself.

Parameters:
distance - a distance indicating how far West of this the returned LongLat position should be. (Or how far East if distance is negative.)
Throws:
java.lang.NullPointerException - if distance is null.

toString

public java.lang.String toString()
Returns a non-null, non-empty string representation of this object for logging and debugging purposes.

The exact details of the representation are unspecified and subject to change.

Overrides:
toString in class java.lang.Object

equals

public boolean equals(java.lang.Object o)
Returns true if o is a LongLat object with the same longitude() and latitude() values as this. Bear in mind that, because of slight inaccuracies introduced by floating-point arithmetic and rounding of longitude/latitude values when transported over XML, it's common for positions that are equal in practical terms to not be equal according to this method.

Overrides:
equals in class java.lang.Object

hashCode

public int hashCode()
Overridden to ensure consistency with equals.

Overrides:
hashCode in class java.lang.Object


www.degreedays.net/api/