feat: add method for final bearing calculation to the Line class

- new method `calculateFinalBearing()`
- add tests
- update documentation

docs/phpgeo.adoc

@@ -112,7 +112,7 @@ The code above will produce the output below:
 The line has a length of 13013.849 meters
 ----
 
-#### Bearing
+==== Bearing
 
 The bearing of an instance can be calculated using the `getBearing()` method.
 An instance of `BearingInterface` must be provided as method argument.
@@ -121,7 +121,6 @@ An instance of `BearingInterface` must be provided as method argument.
 ----
 <?php
 
-use Location\Coordinate;
 use Location\Bearing\BearingEllipsoidal;
 use Location\Coordinate;
 use Location\Line;
@@ -145,6 +144,35 @@ The code above will produce the output below:
 The line has a bearing of 328.67 degrees
 ----
 
+This ist the so called _initial bearing._ There exist another bearing angle,
+called the _final bearing._ It can be calculated as well:
+
+[source,php]
+----
+<?php
+
+use Location\Bearing\BearingEllipsoidal;
+use Location\Coordinate;
+use Location\Line;
+
+$line = new Line(
+    new Coordinate(52.5, 13.5),
+    new Coordinate(52.6, 13.4)
+);
+
+$bearing = $line->getFinalBearing(new BearingEllipsoidal());
+
+printf("The line has a final bearing of %.2f degrees\n", $bearing);
+----
+
+The code above will produce the output below:
+
+----
+The line has a final bearing of 328.59 degrees
+----
+
+See <<Bearing between two points>> for more information about bearings.
+
 === Polyline
 
 A polyline consists of an ordered list of locations, i. e. instances of
@@ -629,6 +657,7 @@ $bearingCalculator = new BearingSpherical();
 
 $startTime = microtime(true);
 var_dump($bearingCalculator->calculateBearing($berlin, $london));
+var_dump($bearingCalculator->calculateFinalBearing($berlin, $london));
 $endTime = microtime(true);
 printf("Time elapsed: %0.6f s\n", ($endTime - $startTime));
 ----
@@ -637,7 +666,8 @@ The code above will produce the following output:
 
 ----
 double(268.60722336693)
-Time elapsed: 0.000268 s
+double(257.85494586285)
+Time elapsed: 0.000285 s
 ----
 
 ===== Calculation with an ellipsoidal earth model
@@ -656,6 +686,7 @@ $bearingCalculator = new BearingEllipsoidal();
 
 $startTime = microtime(true);
 var_dump($bearingCalculator->calculateBearing($berlin, $london));
+var_dump($bearingCalculator->calculateFinalBearing($berlin, $london));
 $endTime = microtime(true);
 printf("Time elapsed: %0.6f s\n", ($endTime - $startTime));
 ----
@@ -664,7 +695,8 @@ The code above will produce the following output:
 
 ----
 double(268.62436347111)
-Time elapsed: 0.000282 s
+double(257.87203657292)
+Time elapsed: 0.000304 s
 ----
 
 Both calculations finish in roughly the same time. One would expect the

src/Location/Line.php

@@ -108,6 +108,16 @@ public function getBearing(BearingInterface $bearingCalculator)
         return $bearingCalculator->calculateBearing($this->point1, $this->point2);
     }
 
+    /**
+     * @param \Location\Bearing\BearingInterface $bearingCalculator
+     *
+     * @return float
+     */
+    public function getFinalBearing(BearingInterface $bearingCalculator)
+    {
+        return $bearingCalculator->calculateFinalBearing($this->point1, $this->point2);
+    }
+
     /**
      * Create a new instance with reversed point order, i. e. reversed direction.
      *

tests/Location/LineTest.php

@@ -53,6 +53,18 @@ public function testIfGetBearingWorksAsExpected()
         $this->assertEquals(90.0, $line->getBearing($bearingCalculator));
     }
 
+    public function testIfGetFinalBearingWorksAsExpected()
+    {
+        $point1 = new Coordinate(0, 0);
+        $point2 = new Coordinate(0, 10);
+
+        $line = new Line($point1, $point2);
+
+        $bearingCalculator = new BearingEllipsoidal();
+
+        $this->assertEquals(90.0, $line->getFinalBearing($bearingCalculator));
+    }
+
     public function testIfGetBearingReversedWorksAsExpected()
     {
         $point1 = new Coordinate(0, 0);
@@ -64,4 +76,16 @@ public function testIfGetBearingReversedWorksAsExpected()
 
         $this->assertEquals(270.0, $line->getBearing($bearingCalculator));
     }
+
+    public function testIfGetFinalBearingReversedWorksAsExpected()
+    {
+        $point1 = new Coordinate(0, 0);
+        $point2 = new Coordinate(0, 10);
+
+        $line = new Line($point2, $point1);
+
+        $bearingCalculator = new BearingEllipsoidal();
+
+        $this->assertEquals(270.0, $line->getFinalBearing($bearingCalculator));
+    }
 }