net.degreedays.geo
Class Distance

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

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

Defines a distance in terms of its numeric value and its unit of measurement (e.g. 20 miles).

To create a Distance object, it's usually easiest to use the static factory methods: metres(double), kilometres(double), feet(double) and miles(double). For example:

 Distance twentyMiles = Distance.miles(20);
 

It's easy to convert between units:

 Distance twentyMilesInMetres = twentyMiles.inMetres();
 

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


Constructor Summary
Distance(double value, DistanceUnit unit)
          Constructs a new Distance object with the specified value and unit of measurement.
 
Method Summary
 boolean equals(java.lang.Object o)
          Returns true if o is a Distance object with an equal unit and an equal value.
static Distance feet(double value)
          Returns a Distance object with the specified value and DistanceUnit.FEET as the unit of measurement.
 int hashCode()
          Overridden to ensure consistency with equals.
 Distance in(DistanceUnit unit)
          Returns a Distance object that represents this Distance converted into the specified unit of measurement.
 Distance inFeet()
          Returns a Distance object that represents this Distance converted into feet.
 Distance inKilometres()
          Returns a Distance object that represents this Distance converted into kilometres.
 Distance inMetres()
          Returns a Distance object that represents this Distance converted into metres.
 Distance inMiles()
          Returns a Distance object that represents this Distance converted into miles.
 int intValue()
          Returns the distance value, rounded to the nearest integer.
static Distance kilometres(double value)
          Returns a Distance object with the specified value and DistanceUnit.KILOMETRES as the unit of measurement.
static Distance metres(double value)
          Returns a Distance object with the specified value and DistanceUnit.METRES as the unit of measurement.
static Distance miles(double value)
          Returns a Distance object with the specified value and DistanceUnit.MILES as the unit of measurement.
 java.lang.String toString()
          Returns a non-null, non-empty string representation of this object for logging and debugging purposes.
 DistanceUnit unit()
          Returns the unit of measurement of this Distance object.
 double value()
          Returns the numeric value of this Distance object.
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Distance

public Distance(double value,
                DistanceUnit unit)
Constructs a new Distance object with the specified value and unit of measurement.

Parameters:
value - the numeric distance (e.g. to create a Distance object representing 20 miles, value should be 20).
unit - the non-null unit of measurement (e.g. DistanceUnit.MILES).
Throws:
java.lang.IllegalArgumentException - if value is NaN or infinite.
java.lang.NullPointerException - if unit is null.
Method Detail

metres

public static Distance metres(double value)
Returns a Distance object with the specified value and DistanceUnit.METRES as the unit of measurement.

Parameters:
value - the number of metres that the returned Distance should represent.
Throws:
java.lang.IllegalArgumentException - if value is NaN or infinite.

feet

public static Distance feet(double value)
Returns a Distance object with the specified value and DistanceUnit.FEET as the unit of measurement.

Parameters:
value - the number of feet that the returned Distance should represent.
Throws:
java.lang.IllegalArgumentException - if value is NaN or infinite.

kilometres

public static Distance kilometres(double value)
Returns a Distance object with the specified value and DistanceUnit.KILOMETRES as the unit of measurement.

Parameters:
value - the number of kilometres that the returned Distance should represent.
Throws:
java.lang.IllegalArgumentException - if value is NaN or infinite.

miles

public static Distance miles(double value)
Returns a Distance object with the specified value and DistanceUnit.MILES as the unit of measurement.

Parameters:
value - the number of miles that the returned Distance should represent.
Throws:
java.lang.IllegalArgumentException - if value is NaN or infinite.

inMetres

public Distance inMetres()
Returns a Distance object that represents this Distance converted into metres.


inKilometres

public Distance inKilometres()
Returns a Distance object that represents this Distance converted into kilometres.


inMiles

public Distance inMiles()
Returns a Distance object that represents this Distance converted into miles.


inFeet

public Distance inFeet()
Returns a Distance object that represents this Distance converted into feet.


in

public Distance in(DistanceUnit unit)
Returns a Distance object that represents this Distance converted into the specified unit of measurement.

For example, Distance.metres(1000).in(DistanceUnit.KILOMETRES) will return a Distance that is equal to Distance.kilometres(1).

Parameters:
unit - the unit of measurement that the returned Distance should have.
Throws:
java.lang.NullPointerException - if unit is null.

unit

public DistanceUnit unit()
Returns the unit of measurement of this Distance object.


value

public double value()
Returns the numeric value of this Distance object.


intValue

public int intValue()
Returns the distance value, rounded to the nearest integer.

Throws:
java.lang.IllegalStateException - if the value stored internally is greater than 2,147,483,647 (the largest allowed int), or less than -2,147,483,648 (the smallest allowed int). Since the smallest distance unit this class works with is feet, and the largest possible integer is over 16 times larger than the circumference of the earth in feet, you are very unlikely to reach the limits of int if you are working with earthly distances.

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 Distance object with an equal unit and an equal value.

This method will never do any conversions between units. So, for example, Distance.kilometres(1).equals(Distance.metres(1000)) will give a value of false.

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/