feat(strings): add explicit string methods

- fromString, fromLonFirstString
- fromLatFirstString
- toString, toLonFirstString
- toLatFirstString

Author: evansiroky

README.md

@@ -28,12 +28,14 @@ No one has agreed on a standard way of representing lon/lat. This is a small nor
     -   [fromLatlng](#fromlatlng)
     -   [fromPoint](#frompoint)
     -   [fromString](#fromstring)
+    -   [fromLatFirstString](#fromlatfirststring)
     -   [isEqual](#isequal)
     -   [print](#print)
     -   [toCoordinates](#tocoordinates)
     -   [toLeaflet](#toleaflet)
     -   [toPoint](#topoint)
     -   [toString](#tostring)
+    -   [toLatFirstString](#tolatfirststring)
 -   [lonlat.types.output](#lonlattypesoutput)
 
 ### lonlat.types.input
@@ -177,20 +179,41 @@ Returns **[lonlat.types.output](#lonlattypesoutput)**
 
 #### fromString
 
-Tries to parse from a string.
+<b>aliases:</b> fromLonFirstString<br>
+
+Tries to parse from a string where the longitude appears before the latitude.
 
 **Parameters**
 
 -   `str` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** A string in the format: `longitude,latitude`
--   `latIsFirst` **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)?** Whether or not the first value is latitude. (optional, default `false`)
 
 **Examples**
 
 ```javascript
 var lonlat = require('@conveyal/lonlat')
 
-var position = lonlat.fromString('12,34')        // { lon: 12, lat: 34 }
-var position = lonlat.fromString('12,34', true)  // { lon: 34, lat: 12 }
+var position = lonlat.fromString('12,34')          // { lon: 12, lat: 34 }
+var position = lonlat.fromLonFirstString('12,34')  // { lon: 12, lat: 34 }
+```
+
+-   Throws **[lonlat.types.InvalidCoordinateException](#lonlattypesinvalidcoordinateexception)** 
+
+Returns **[lonlat.types.output](#lonlattypesoutput)** 
+
+#### fromLatFirstString
+
+Tries to parse from a string where the latitude appears before the longitude.
+
+**Parameters**
+
+-   `str` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** A string in the format: `latitude,longitude`
+
+**Examples**
+
+```javascript
+var lonlat = require('@conveyal/lonlat')
+
+var position = lonlat.fromLatFirstString('12,34) // { lon: 34, lat: 12 }
 ```
 
 -   Throws **[lonlat.types.InvalidCoordinateException](#lonlattypesinvalidcoordinateexception)** 
@@ -304,7 +327,30 @@ Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refer
 
 #### toString
 
-Translates to coordinate string.
+<b>aliases:</b> toLonFirstString<br>
+
+Translates to coordinate string where the longitude appears before latitude.
+
+**Parameters**
+
+-   `input` **[lonlat.types.input](#lonlattypesinput)** 
+
+**Examples**
+
+```javascript
+var lonlat = require('@conveyal/lonlat')
+
+var str = lonlat.toString({ lat: 12, longitude: 34 })          // '34,12'
+var str = lonlat.toLonFirstString({ lat: 12, longitude: 34 })  // '34,12'
+```
+
+-   Throws **[lonlat.types.InvalidCoordinateException](#lonlattypesinvalidcoordinateexception)** 
+
+Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** A string in the format 'longitude,latitude'
+
+#### toLatFirstString
+
+Translates to coordinate string where the latitude appears before longitude.
 
 **Parameters**
 
@@ -315,7 +361,7 @@ Translates to coordinate string.
 ```javascript
 var lonlat = require('@conveyal/lonlat')
 
-var str = lonlat.toString({ lat: 12, longitude: 34 })   // '34,12'
+var str = lonlat.toLatFirstString({ lat: 12, longitude: 34 })  // '12,34'
 ```
 
 -   Throws **[lonlat.types.InvalidCoordinateException](#lonlattypesinvalidcoordinateexception)** 

index.js

@@ -126,26 +126,43 @@ function fromPoint (point) {
 module.exports.fromPoint = fromPoint
 
 /**
- * Tries to parse from a string.
+ * <b>aliases:</b> fromLonFirstString<br>
+ *
+ * Tries to parse from a string where the longitude appears before the latitude.
+ *
+ * @memberof conveyal/lonlat
+ * @param  {string} str          A string in the format: `longitude,latitude`
+ * @return {lonlat.types.output}
+ * @throws {lonlat.types.InvalidCoordinateException}
+ * @example
+ * var lonlat = require('@conveyal/lonlat')
+
+ var position = lonlat.fromString('12,34')          // { lon: 12, lat: 34 }
+ var position = lonlat.fromLonFirstString('12,34')  // { lon: 12, lat: 34 }
+ */
+function fromString (str) {
+  var arr = str.split(',')
+  return floatize({lon: arr[0], lat: arr[1]})
+}
+module.exports.fromString = module.exports.fromLonFirstString = fromString
+
+/**
+ * Tries to parse from a string where the latitude appears before the longitude.
  *
  * @memberof conveyal/lonlat
- * @param  {string} str                 A string in the format: `longitude,latitude`
- * @param  {boolean} [latIsFirst=false] Whether or not the first value is latitude.
+ * @param  {string} str           A string in the format: `latitude,longitude`
  * @return {lonlat.types.output}
  * @throws {lonlat.types.InvalidCoordinateException}
  * @example
  * var lonlat = require('@conveyal/lonlat')
 
- var position = lonlat.fromString('12,34')        // { lon: 12, lat: 34 }
- var position = lonlat.fromString('12,34', true)  // { lon: 34, lat: 12 }
+ var position = lonlat.fromLatFirstString('12,34) // { lon: 34, lat: 12 }
  */
-function fromString (str, latIsFirst) {
+function fromLatFirstString (str) {
   var arr = str.split(',')
-  return latIsFirst
-    ? floatize({lat: arr[0], lon: arr[1]})
-    : floatize({lon: arr[0], lat: arr[1]})
+  return floatize({lat: arr[0], lon: arr[1]})
 }
-module.exports.fromString = fromString
+module.exports.fromLatFirstString = fromLatFirstString
 
 /**
  * Determine if two inputs are equal to each other
@@ -236,21 +253,40 @@ module.exports.toPoint = function toPoint (input) {
 }
 
 /**
- * Translates to coordinate string.
+ * <b>aliases:</b> toLonFirstString<br>
+ *
+ * Translates to coordinate string where the longitude appears before latitude.
  *
  * @param {lonlat.types.input} input
  * @return {string}     A string in the format 'longitude,latitude'
  * @throws {lonlat.types.InvalidCoordinateException}
  * @example
  * var lonlat = require('@conveyal/lonlat')
 
- var str = lonlat.toString({ lat: 12, longitude: 34 })   // '34,12'
+ var str = lonlat.toString({ lat: 12, longitude: 34 })          // '34,12'
+ var str = lonlat.toLonFirstString({ lat: 12, longitude: 34 })  // '34,12'
  */
-module.exports.toString = function toString (input) {
+module.exports.toString = module.exports.toLonFirstString = function toString (input) {
   var ll = normalize(input)
   return ll.lon + ',' + ll.lat
 }
 
+/**
+ * Translates to coordinate string where the latitude appears before longitude.
+ *
+ * @param {lonlat.types.input} input
+ * @return {string}     A string in the format 'longitude,latitude'
+ * @throws {lonlat.types.InvalidCoordinateException}
+ * @example
+ * var lonlat = require('@conveyal/lonlat')
+
+ var str = lonlat.toLatFirstString({ lat: 12, longitude: 34 })  // '12,34'
+ */
+module.exports.toLatFirstString = function toLatFirstString (input) {
+  var ll = normalize(input)
+  return ll.lat + ',' + ll.lon
+}
+
 function floatize (lonlat) {
   var lon = parseFloatWithAlternates([lonlat.lon, lonlat.lng, lonlat.longitude])
   var lat = parseFloatWithAlternates([lonlat.lat, lonlat.latitude])

index.test.js

@@ -72,6 +72,12 @@ describe('lonlat', () => {
     }, {
       expected: str,
       method: 'toString'
+    }, {
+      expected: str,
+      method: 'toLonFirstString'
+    }, {
+      expected: strLatFirst,
+      method: 'toLatFirstString'
     }]
 
     testCases.forEach((test) => {
@@ -87,15 +93,21 @@ describe('lonlat', () => {
       description: 'Object with lng and lat keys'
     }, {
       calculated: ll.fromCoordinates(coordinates),
-      description: 'Array of lon and lat'
+      description: 'Array of lon and lat (fromCoordinates)'
+    }, {
+      calculated: ll.fromGeoJSON(coordinates),
+      description: 'Array of lon and lat (fromGeoJSON)'
     }, {
       calculated: ll.fromPoint(point),
       description: 'Object with x and y keys'
     }, {
       calculated: ll.fromString(str),
-      description: 'String with comma separating lon and lat, respectively'
+      description: 'String with comma separating lon and lat, respectively (fromString)'
+    }, {
+      calculated: ll.fromLonFirstString(str),
+      description: 'String with comma separating lon and lat, respectively (fromLonFirstString)'
     }, {
-      calculated: ll.fromString(strLatFirst, true),
+      calculated: ll.fromLatFirstString(strLatFirst),
       description: 'String with comma separating lat and lon, respectively'
     }]