New function convertDistance @turf/helpers; (#732)

* - added convertDistance to @turf/helpers;
- added test for distanceToDegrees;
- added input validation to round;
- added centimeters as a valid unit;

* Update Readme docs

* Update contributors

packages/turf-helpers/README.md

@@ -249,6 +249,7 @@ Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refer
 # radiansToDistance
 
 Convert a distance measurement (assuming a spherical Earth) from radians to a more friendly unit.
+Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
 
 **Parameters**
 
@@ -260,6 +261,7 @@ Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refer
 # distanceToRadians
 
 Convert a distance measurement (assuming a spherical Earth) from a real-world unit into radians
+Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
 
 **Parameters**
 
@@ -271,6 +273,7 @@ Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refer
 # distanceToDegrees
 
 Convert a distance measurement (assuming a spherical Earth) from a real-world unit into degrees
+Valid units: miles, nauticalmiles, inches, yards, meters, metres, centimeters, kilometres, feet
 
 **Parameters**
 
@@ -310,6 +313,19 @@ Converts an angle in degrees to radians
 
 Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** angle in radians
 
+# convertDistance
+
+Converts a distance to the requested unit.
+Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
+
+**Parameters**
+
+-   `distance` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** to be converted
+-   `originalUnit` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** of the distance
+-   `finalUnit` **\[[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)]** returned unit (optional, default `kilometers`)
+
+Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** the converted distance
+
 <!-- This file is automatically generated. Please don't edit it directly:
 if you find an error, edit the source file (likely index.js), and re-run
 ./scripts/generate-readmes in the turf project. -->

packages/turf-helpers/index.js

@@ -264,6 +264,8 @@ var factors = {
     yards: 6969600,
     meters: 6373000,
     metres: 6373000,
+    centimeters: 6.373e+8,
+    centimetres: 6.373e+8,
     kilometers: 6373,
     kilometres: 6373,
     feet: 20908792.65
@@ -283,12 +285,15 @@ var factors = {
  * //=120.43
  */
 function round(num, precision) {
+    if (num === undefined || num === null || isNaN(num)) throw new Error('num is required');
+    if (precision && !(precision >= 0)) throw new Error('precision must be a positive number');
     var multiplier = Math.pow(10, precision || 0);
     return Math.round(num * multiplier) / multiplier;
 }
 
 /**
  * Convert a distance measurement (assuming a spherical Earth) from radians to a more friendly unit.
+ * Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
  *
  * @name radiansToDistance
  * @param {number} radians in radians across the sphere
@@ -305,6 +310,7 @@ function radiansToDistance(radians, units) {
 
 /**
  * Convert a distance measurement (assuming a spherical Earth) from a real-world unit into radians
+ * Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
  *
  * @name distanceToRadians
  * @param {number} distance in real units
@@ -321,6 +327,7 @@ function distanceToRadians(distance, units) {
 
 /**
  * Convert a distance measurement (assuming a spherical Earth) from a real-world unit into degrees
+ * Valid units: miles, nauticalmiles, inches, yards, meters, metres, centimeters, kilometres, feet
  *
  * @name distanceToDegrees
  * @param {number} distance in real units
@@ -375,6 +382,25 @@ function degrees2radians(degrees) {
     return radians * Math.PI / 180;
 }
 
+
+/**
+ * Converts a distance to the requested unit.
+ * Valid units: miles, nauticalmiles, inches, yards, meters, metres, kilometers, centimeters, feet
+ *
+ * @param {number} distance to be converted
+ * @param {string} originalUnit of the distance
+ * @param {string} [finalUnit=kilometers] returned unit
+ * @returns {number} the converted distance
+ */
+function convertDistance(distance, originalUnit, finalUnit) {
+    if (distance === null || distance === undefined) throw new Error('distance is required');
+    if (!(distance >= 0)) throw new Error('distance must be a positive number');
+
+    var convertedDistance = radiansToDistance(distanceToRadians(distance, originalUnit), finalUnit || 'kilometers');
+    return convertedDistance;
+}
+
+
 module.exports = {
     feature: feature,
     featureCollection: featureCollection,
@@ -391,5 +417,6 @@ module.exports = {
     radians2degrees: radians2degrees,
     degrees2radians: degrees2radians,
     bearingToAngle: bearingToAngle,
+    convertDistance: convertDistance,
     round: round
 };

packages/turf-helpers/package.json

@@ -23,6 +23,11 @@
     "geojson"
   ],
   "author": "Turf Authors",
+  "contributors": [
+    "Tom MacWright <@tmcw>",
+    "Stefano Borghi <@stebogit>",
+    "Denis Carriere <@DenisCarriere>"
+  ],
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/Turfjs/turf/issues"

packages/turf-helpers/test.js

@@ -15,6 +15,7 @@ const {
     radians2degrees,
     degrees2radians,
     bearingToAngle,
+    convertDistance,
     round
 } = require('./');
 
@@ -317,19 +318,25 @@ test('distanceToRadians', t => {
     t.end();
 });
 
+test('distanceToDegrees', t => {
+    t.equal(distanceToDegrees(1, 'radians'), 57.29577951308232);
+    t.equal(distanceToDegrees(100, 'kilometers'), 0.8990393772647469);
+    t.equal(distanceToDegrees(10, 'miles'), 0.14468631190172304);
+    t.throws(() => distanceToRadians(1, 'foo'), 'invalid units');
+    t.end();
+});
+
 test('radians2degrees', t => {
     t.equal(round(radians2degrees(Math.PI / 3), 6), 60, 'radiance conversion PI/3');
     t.equal(radians2degrees(3.5 * Math.PI), 270, 'radiance conversion 3.5PI');
     t.equal(radians2degrees(-Math.PI), -180, 'radiance conversion -PI');
-
     t.end();
 });
 
 test('radians2degrees', t => {
     t.equal(degrees2radians(60), Math.PI / 3, 'degrees conversion 60');
     t.equal(degrees2radians(270), 1.5 * Math.PI, 'degrees conversion 270');
     t.equal(degrees2radians(-180), -Math.PI, 'degrees conversion -180');
-
     t.end();
 });
 
@@ -339,14 +346,24 @@ test('bearingToAngle', t => {
     t.equal(bearingToAngle(410), 50);
     t.equal(bearingToAngle(-200), 160);
     t.equal(bearingToAngle(-395), 325);
-
     t.end();
 });
 
 test('round', t => {
     t.equal(round(125.123), 125);
     t.equal(round(123.123, 1), 123.1);
     t.equal(round(123.5), 124);
+    t.throws(() => round(34.5, 'precision'), 'invalid precision');
+    t.throws(() => round(34.5, -5), 'invalid precision');
+    t.end();
+});
 
+test('convertDistance', t => {
+    t.equal(convertDistance(1000, 'meters'), 1);
+    t.equal(convertDistance(1, 'kilometers', 'miles'), 0.6213714106386318);
+    t.equal(convertDistance(1, 'miles', 'kilometers'), 1.6093434343434343);
+    t.equal(convertDistance(1, 'nauticalmiles'), 1.851999843075488);
+    t.equal(convertDistance(1, 'meters', 'centimeters'), 100);
+    t.throws(() => convertDistance(1, 'foo'), 'invalid units');
     t.end();
 });