Distance (Degree Days.net API JavaDoc)

java.lang.Object
- 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

Constructors
Constructor and Description

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

Constructors
Constructor and Description
`Distance(double value, DistanceUnit unit)` Constructs a new `Distance` object with the specified value and unit of measurement.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`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

Class Distance

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Distance

Method Detail

metres

feet

kilometres

miles

inMetres

inKilometres

inMiles

inFeet

in

unit

value

intValue

toString

equals

hashCode