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 github@loverde.org.

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 );
  }