From 61e6d36181dd6b97784c50306f8ee020afc9bd17 Mon Sep 17 00:00:00 2001 From: Kurtis LoVerde Date: Mon, 15 Feb 2016 11:31:41 -0500 Subject: [PATCH] Renamed DistanceCalculator.totalTravelDistance(Unit, Point...) to DistanceCalculator.distance(Unit, Point...). Deprecated DistanceCalculator.distance(Point, Point, Unit). Updated README and javadoc. --- CHANGELOG.md | 6 +++++ README.md | 11 +++++---- gradle.properties | 4 ++-- .../DistanceCalculator.java | 23 ++++++++++++------- .../DistanceCalculatorTest.java | 11 ++++++--- 5 files changed, 38 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0873c06..817bb64 100644 --- a/CHANGELOG.md +++ b/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.). diff --git a/README.md b/README.md index 98875d8..02e8ced 100644 --- a/README.md +++ b/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. diff --git a/gradle.properties b/gradle.properties index 8eab62e..0c4cec2 100644 --- a/gradle.properties +++ b/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 diff --git a/src/main/java/org/loverde/geographiccoordinate/DistanceCalculator.java b/src/main/java/org/loverde/geographiccoordinate/DistanceCalculator.java index be58d3b..2156b98 100644 --- a/src/main/java/org/loverde/geographiccoordinate/DistanceCalculator.java +++ b/src/main/java/org/loverde/geographiccoordinate/DistanceCalculator.java @@ -7,6 +7,7 @@ + /** *

* 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 /** *

- * 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)}. *

* *

@@ -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; } diff --git a/src/test/java/org/loverde/geographiccoordinate/DistanceCalculatorTest.java b/src/test/java/org/loverde/geographiccoordinate/DistanceCalculatorTest.java index e39c3fe..c242261 100644 --- a/src/test/java/org/loverde/geographiccoordinate/DistanceCalculatorTest.java +++ b/src/test/java/org/loverde/geographiccoordinate/DistanceCalculatorTest.java @@ -32,25 +32,30 @@ 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) ); @@ -58,7 +63,7 @@ public void testDistance_bothMethodsCalculateSameValues() { /** *

- * 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. *

* @@ -79,7 +84,7 @@ public void testDistance_bothMethodsCalculateSameValues() { * @see Shortened trip URL - Who knows how long this will exist before Bing deletes it... * @see Full trip URL - 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 ); }