Renamed DistanceCalculator.totalTravelDistance(Unit, Point...) to

DistanceCalculator.distance(Unit, Point...).  Deprecated
DistanceCalculator.distance(Point, Point, Unit).  Updated README and
javadoc.

CHANGELOG.md

@@ -1,3 +1,9 @@
+## Release 1.2.1 (February 15, 2016)
+
+* Renamed the new method from today's earlier release:  DistanceCalculator.totalTravelDistance( Unit, Point ... ) method is now DistanceCalculator.distance( Unit, Point ... ).
+* Deprecated DistanceCalculator.distance( Point, Point, Unit ), as it has been rendered redundant by the vararg method above.  *This deprecated method will be removed in the near future - possibly in the next release.*
+* Updated README and javadoc
+
 ## Release 1.2 (February 15, 2016)
 
 * Added a totalTravelDistance method to DistanceCalculator.  This method calculates the total distance traveled between an unlimited number of points (A to B to C, etc.).

README.md

@@ -1,10 +1,13 @@
 GeographicCoordinate
 ====================
 
-GeographicCoordinate is a simple Java library for latitude and longitude.
+GeographicCoordinate is a simple Java library for representing latitude and longitude, and for calculating distances.
 
 Features:
 
-* Unlike using floating-point primitives, enforces automatic range checking:  objects can never have invalid values
-* Coordinates can be manipulated in floating-point form or as degrees, minutes and seconds
-* Provides the ability to calculate the distance between two or more coordinates
+* Unlike using floating-point primitives, GeographicCoordinate enforces automatic range checking:  objects can never have invalid values.
+* Coordinates can be manipulated in floating-point form or as degrees, minutes and seconds.
+* Provides the ability to calculate the distance between two coordinates, or for the total travel distance between an unlimited number of points.
+
+
+If you find this library useful, I'd love to hear from you.  I can be reached at [email protected].

gradle.properties

@@ -6,8 +6,8 @@ buildScriptsDir=../BuildScripts
 # BuildScripts configuration
 
 projectName=GeographicCoordinate
-releaseVersion=1.2
-specVersion=1.2
+releaseVersion=1.2.1
+specVersion=1.2.1
 javaSourceCompatibility=1.6
 javaTargetCompatibility=1.6
 jarName=geographiccoordinate

src/main/java/org/loverde/geographiccoordinate/DistanceCalculator.java

@@ -7,6 +7,7 @@
 
 
 
+
 /**
  * <p>
  * This class calculates the distance bewteen two sets of coordinates as the crow
@@ -97,10 +98,11 @@ private Unit( final double perKilometer ) {
     * @param unit The unit of measurement
     *
     * @return The distance between {@code point1} and {@code point2}, expressed in terms of {@code unit}
+    *
+    * @deprecated This method will be removed in the near future - possibly in the next release.  Use {@link #distance(Unit, Point...) distance(Unit, Point...)}
     */
+   @Deprecated
    public static double distance( final Point point1, final Point point2, final Unit unit ) {
-      if( point1 == null ) throw new IllegalArgumentException( "Point 1 is null" );
-      if( point2 == null ) throw new IllegalArgumentException( "Point 2 is null" );
 
       return distance( point1.getLatitude(), point1.getLongitude(),
                        point2.getLatitude(), point2.getLongitude(),
@@ -109,9 +111,10 @@ public static double distance( final Point point1, final Point point2, final Uni
 
    /**
     * <p>
-    * Gets the total travel distance for an unlimited number of points.  For example, if the distance from
-    * point A to point B is 3, and the distance from point B to point C is 2, the total distance
-    * traveled will be (3 + 2) = 5.  Just pass {@linkplain Point}s in the order in which they're visited.
+    * Gets the total distance between an unlimited number of {@linkplain Point}s.  For example, if the
+    * distance from point A to point B is 3, and the distance from point B to point C is 2, the total
+    * distance traveled will be (3 + 2) = 5.  Just pass {@code Point}s in the order in which they're
+    * visited.  This is equivalent to repeatedly calling {@link DistanceCalculator#distance(Latitude, Longitude, Latitude, Longitude, Unit)}.
     * </p>
     *
     * <p><strong>
@@ -126,9 +129,9 @@ public static double distance( final Point point1, final Point point2, final Uni
     * @param unit The unit of measurement
     * @param points A vararg of {@linkplain Point}s arranged in the order in which the points are visited
     *
-    * @return The total distance traveled
+    * @return The total distance traveled, expressed in terms of {@code unit}
     */
-   public static double totalTravelDistance( final Unit unit, final Point ... points ) {
+   public static double distance( final Unit unit, final Point ... points ) {
       if( points == null ) throw new IllegalArgumentException( "Points are null" );
       if( points.length < 2 ) throw new IllegalArgumentException( "Need to provide at least 2 points" );
 
@@ -137,7 +140,11 @@ public static double totalTravelDistance( final Unit unit, final Point ... point
 
       for( int i = 1; i < points.length; i++ ) {
          final Point current = points[i];
-         distance += distance( previous, current, unit );
+
+         if( previous == null ) throw new IllegalArgumentException( "points " + (i - 1) + " is null" );
+         if( current == null ) throw new IllegalArgumentException( "points " + i + " is null" );
+
+         distance += distance( previous.getLatitude(), previous.getLongitude(), current.getLatitude(), current.getLongitude(), unit );
          previous = current;
       }
 

src/test/java/org/loverde/geographiccoordinate/DistanceCalculatorTest.java

@@ -32,33 +32,38 @@ public void setUp() throws GeographicCoordinateException {
    }
 
    public void testDistance_kilometers() {
+      @SuppressWarnings( "deprecation" )
       final double distance = DistanceCalculator.distance( point1, point2, DistanceCalculator.Unit.KILOMETERS );
       assertEquals( 326.3834438586294d, distance );
    }
 
    public void testDistance_meters() {
+      @SuppressWarnings( "deprecation" )
       final double distance = DistanceCalculator.distance( point1, point2, DistanceCalculator.Unit.METERS );
       assertEquals( 326383.4438586294d, distance );
    }
 
    public void testDistance_miles() {
+      @SuppressWarnings( "deprecation" )
       final double distance = DistanceCalculator.distance( point1, point2, DistanceCalculator.Unit.MILES );
       assertEquals( 202.8052696369635d, distance );
    }
 
    public void testDistance_nauticalMiles() {
+      @SuppressWarnings( "deprecation" )
       final double distance = DistanceCalculator.distance( point1, point2, DistanceCalculator.Unit.NAUTICAL_MILES );
       assertEquals( 176.23296104677613d, distance );
    }
 
+   @SuppressWarnings( "deprecation" )
    public void testDistance_bothMethodsCalculateSameValues() {
       assertEquals( DistanceCalculator.distance(point1, point2, Unit.KILOMETERS),
                     DistanceCalculator.distance( latitude1, longitude1, latitude2, longitude2, Unit.KILOMETERS) );
    }
 
    /**
     * <p>
-    * Uses interpolation to approximate a 95.5-mile trip along Route 5 in California, from (35.048983, -118.987977)
+    * Uses interpolation to approximate a 95.5-mile trip along Interstate 5 in California, from (35.048983, -118.987977)
     * to (36.078247, -120.103787).  The trip distance and all coordinates are as reported by Bing Maps on February 15, 2016.
     * </p>
     *
@@ -79,7 +84,7 @@ public void testDistance_bothMethodsCalculateSameValues() {
     * @see <a href="http://binged.it/1SPhHjq">Shortened trip URL</a>  - Who knows how long this will exist before Bing deletes it...
     * @see <a href="http://www.bing.com/mapspreview?&ty=0&rtp=pos.35.048992_-118.987968_I-5%20N%2c%20Bakersfield%2c%20CA%2093307_I-5%20N%2c%20Bakersfield%2c%20CA%2093307__e_~pos.36.078312_-120.103737_I-5%20N%2c%20Huron%2c%20CA%2093234_I-5%20N%2c%20Huron%2c%20CA%2093234__e_&mode=d&u=0&tt=I-5%20N%2c%20Bakersfield%2c%20CA%2093307%20to%20I-5%20N%2c%20Huron%2c%20CA%2093234&tsts2=%2526ty%253d18%2526q%253d35.04899226103765%25252c-118.98797131369996%2526mb%253d36.379826~-121.444888~34.715083~-117.418399&tstt2=I-5%20N%2c%20Bakersfield%2c%20CA%2093307&tsts1=%2526ty%253d0%2526rtp%253dpos.35.048992_-118.987968_I-5%252520N%25252c%252520Bakersfield%25252c%252520CA%25252093307_I-5%252520N%25252c%252520Bakersfield%25252c%252520CA%25252093307__e_~pos.36.078312_-120.103737_I-5%252520N%25252c%252520Huron%25252c%252520CA%25252093234_I-5%252520N%25252c%252520Huron%25252c%252520CA%25252093234__e_%2526mode%253dd%2526u%253d0&tstt1=I-5%20N%2c%20Bakersfield%2c%20CA%2093307%20to%20I-5%20N%2c%20Huron%2c%20CA%2093234&tsts0=%2526ty%253d18%2526q%253d36.07831163070724%25252c-120.1037394074518%2526mb%253d36.084772~-120.119465~36.071852~-120.088008&tstt0=I-5%20N%2c%20Huron%2c%20CA%2093234&cp=36.078659~-120.107106&lvl=16&ftst=1&ftics=True&v=2&sV=1&form=S00027">Full trip URL</a> - Use this if the shortened URL doesn't work.  This URL is so ridiculous, there's no telling how long it will actually work before Bing changes the URL format.
     */
-   public void testTotalTravelDistance() throws GeographicCoordinateException {
+   public void testVarargDistance() throws GeographicCoordinateException {
       Point points[] = new Point[20];
       int idx = 0;
 
@@ -104,7 +109,7 @@ public void testTotalTravelDistance() throws GeographicCoordinateException {
       points[idx++] = new Point( new Latitude(36.028889d), new Longitude(-120.019310d) );
       points[idx++] = new Point( new Latitude(36.078247d), new Longitude(-120.103787d) );
 
-      final double distance = DistanceCalculator.totalTravelDistance( Unit.MILES, points );
+      final double distance = DistanceCalculator.distance( Unit.MILES, points );
 
       assertEquals( 95.5d, distance, .026d );
    }