diff --git a/README.md b/README.md index b446980..6827880 100644 --- a/README.md +++ b/README.md @@ -21,8 +21,8 @@ No one has agreed on a standard way of representing lon/lat. This is a small nor #### Table of Contents -- [input](#input) -- [InvalidCoordinateException](#invalidcoordinateexception) +- [lonlat.types.input](#lonlattypesinput) +- [lonlat.types.InvalidCoordinateException](#lonlattypesinvalidcoordinateexception) - [conveyal/lonlat](#conveyallonlat) - [fromCoordinates](#fromcoordinates) - [fromLatlng](#fromlatlng) @@ -34,9 +34,9 @@ No one has agreed on a standard way of representing lon/lat. This is a small nor - [toLeaflet](#toleaflet) - [toPoint](#topoint) - [toString](#tostring) -- [lonlat](#lonlat) +- [lonlat.types.output](#lonlattypesoutput) -### input +### lonlat.types.input (type) @@ -57,7 +57,7 @@ Type: ([Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference - `unknown` -### InvalidCoordinateException +### lonlat.types.InvalidCoordinateException (exception type) @@ -75,7 +75,7 @@ Parse an unknown type of input. **Parameters** -- `unknown` **[input](#input)** +- `unknown` **[lonlat.types.input](#lonlattypesinput)** **Examples** @@ -104,9 +104,9 @@ position = lonlat({}) // Error: Invalid latitude value: und position = lonlat(null) // Error: Value must not be null or undefined ``` -- Throws **[InvalidCoordinateException](#invalidcoordinateexception)** +- Throws **[lonlat.types.InvalidCoordinateException](#lonlattypesinvalidcoordinateexception)** -Returns **[lonlat](#lonlat)** +Returns **[lonlat.types.output](#lonlattypesoutput)** #### fromCoordinates @@ -127,9 +127,9 @@ var position = lonlat.fromCoordinates([12, 34]) // { lon: 12, lat: 34 } position = lonlat.fromGeoJSON([12, 34]) // { lon: 12, lat: 34 } ``` -- Throws **[InvalidCoordinateException](#invalidcoordinateexception)** +- Throws **[lonlat.types.InvalidCoordinateException](#lonlattypesinvalidcoordinateexception)** -Returns **[lonlat](#lonlat)** +Returns **[lonlat.types.output](#lonlattypesoutput)** #### fromLatlng @@ -150,9 +150,9 @@ var position = lonlat.fromLatlng({ longitude: 12, latitude: 34 }) // { lon: 12 position = lonlat.fromLeaflet({ lng: 12, lat: 34 }) // { lon: 12, lat: 34 } ``` -- Throws **[InvalidCoordinateException](#invalidcoordinateexception)** +- Throws **[lonlat.types.InvalidCoordinateException](#lonlattypesinvalidcoordinateexception)** -Returns **[lonlat](#lonlat)** +Returns **[lonlat.types.output](#lonlattypesoutput)** #### fromPoint @@ -171,9 +171,9 @@ var lonlat = require('@conveyal/lonlat') var position = lonlat.fromPoint({ x: 12, y: 34 }) // { lon: 12, lat: 34 } ``` -- Throws **[InvalidCoordinateException](#invalidcoordinateexception)** +- Throws **[lonlat.types.InvalidCoordinateException](#lonlattypesinvalidcoordinateexception)** -Returns **[lonlat](#lonlat)** +Returns **[lonlat.types.output](#lonlattypesoutput)** #### fromString @@ -182,18 +182,20 @@ Tries to parse from a string. **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') // { lon: 12, lat: 34 } +var position = lonlat.fromString('12,34', true) // { lon: 34, lat: 12 } ``` -- Throws **[InvalidCoordinateException](#invalidcoordinateexception)** +- Throws **[lonlat.types.InvalidCoordinateException](#lonlattypesinvalidcoordinateexception)** -Returns **[lonlat](#lonlat)** +Returns **[lonlat.types.output](#lonlattypesoutput)** #### isEqual @@ -201,9 +203,9 @@ Determine if two inputs are equal to each other **Parameters** -- `lonlat1` **[input](#input)** -- `lonlat2` **[input](#input)** -- `epsilon` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?** The maximum acceptable deviation to be considered equal. Default = 0 +- `lonlat1` **input** +- `lonlat2` **input** +- `epsilon` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?** The maximum acceptable deviation to be considered equal. (optional, default `0`) **Examples** @@ -213,7 +215,7 @@ var lonlat = require('@conveyal/lonlat') var isEqual = lonlat.isEqual('12,34', [12, 34]) // true ``` -- Throws **[InvalidCoordinateException](#invalidcoordinateexception)** +- Throws **[lonlat.types.InvalidCoordinateException](#lonlattypesinvalidcoordinateexception)** Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** @@ -221,8 +223,8 @@ Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refe **Parameters** -- `input` **[input](#input)** -- `fixed` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?** The number of decimal places to round to. +- `input` **input** +- `fixed` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)?** The number of decimal places to round to. (optional, default `5`) **Examples** @@ -232,7 +234,7 @@ var lonlat = require('@conveyal/lonlat') var pretty = lonlat.print('12.345678,34') // '12.34568, 34.00000' ``` -- Throws **[InvalidCoordinateException](#invalidcoordinateexception)** +- Throws **[lonlat.types.InvalidCoordinateException](#lonlattypesinvalidcoordinateexception)** Returns **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** A string with in the format `longitude,latitude` rounded to the number of decimal places as specified by `fixed` @@ -245,7 +247,7 @@ Translates to a coordinate array. **Parameters** -- `input` **[input](#input)** +- `input` **[lonlat.types.input](#lonlattypesinput)** **Examples** @@ -255,7 +257,7 @@ var lonlat = require('@conveyal/lonlat') var coords = lonlat.toCoordinates('12,34') // [12, 34] ``` -- Throws **[InvalidCoordinateException](#invalidcoordinateexception)** +- Throws **[lonlat.types.InvalidCoordinateException](#lonlattypesinvalidcoordinateexception)** Returns **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)** An array in the format [longitude, latitude] @@ -266,7 +268,7 @@ This function requires Leaflet to be installed as a global variable `L` in the w **Parameters** -- `input` **[input](#input)** +- `input` **[lonlat.types.input](#lonlattypesinput)** **Examples** @@ -276,7 +278,7 @@ var lonlat = require('@conveyal/lonlat') var position = lonlat.toLeaflet({ lat: 12, long: 34 }) // Leaflet LatLng object ``` -- Throws **[InvalidCoordinateException](#invalidcoordinateexception)** +- Throws **[lonlat.types.InvalidCoordinateException](#lonlattypesinvalidcoordinateexception)** Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** A Leaflet LatLng object @@ -286,7 +288,7 @@ Translates to point Object. **Parameters** -- `input` **[input](#input)** +- `input` **[lonlat.types.input](#lonlattypesinput)** **Examples** @@ -296,7 +298,7 @@ var lonlat = require('@conveyal/lonlat') var point = lonlat.toPoint('12,34') // { x: 12, y: 34 } ``` -- Throws **[InvalidCoordinateException](#invalidcoordinateexception)** +- Throws **[lonlat.types.InvalidCoordinateException](#lonlattypesinvalidcoordinateexception)** Returns **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)** An object with `x` and `y` attributes representing latitude and longitude respectively @@ -306,7 +308,7 @@ Translates to coordinate string. **Parameters** -- `input` **[input](#input)** +- `input` **[lonlat.types.input](#lonlattypesinput)** **Examples** @@ -316,11 +318,11 @@ var lonlat = require('@conveyal/lonlat') var str = lonlat.toString({ lat: 12, longitude: 34 }) // '34,12' ``` -- Throws **[InvalidCoordinateException](#invalidcoordinateexception)** +- 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' -### lonlat +### lonlat.types.output (type) diff --git a/index.js b/index.js index 2e5d313..f2063d3 100644 --- a/index.js +++ b/index.js @@ -10,14 +10,14 @@ * The properties can be named various things. * For longitude any of the following are valid: `lon`, `lng` or `longitude` * For latitude any of the following are valid: `lat` or `latitude` - * @typedef {Array|string|Object} input + * @typedef {Array|string|Object} lonlat.types.input */ /** * (type) * * Standardized lon/lat object. - * @typedef {Object} lonlat + * @typedef {Object} lonlat.types.output * @property {number} lat * @property {number} lon */ @@ -26,16 +26,16 @@ * (exception type) * * An error that is thrown upon providing invalid coordinates. - * @typedef {Error} InvalidCoordinateException + * @typedef {Error} lonlat.types.InvalidCoordinateException */ /** * Parse an unknown type of input. * * @module conveyal/lonlat - * @param {input} unknown - * @return {lonlat} - * @throws {InvalidCoordinateException} + * @param {lonlat.types.input} unknown + * @return {lonlat.types.output} + * @throws {lonlat.types.InvalidCoordinateException} * @example * var lonlat = require('@conveyal/lonlat') @@ -76,8 +76,8 @@ module.exports = normalize * * @memberof conveyal/lonlat * @param {Array} coordinates An array in the format: [longitude, latitude] - * @return {lonlat} - * @throws {InvalidCoordinateException} + * @return {lonlat.types.output} + * @throws {lonlat.types.InvalidCoordinateException} * @example * var lonlat = require('@conveyal/lonlat') @@ -95,8 +95,8 @@ module.exports.fromCoordinates = module.exports.fromGeoJSON = fromCoordinates * Tries to parse from an object. * * @param {Object} lonlat An object with a `lon`, `lng` or `longitude` attribute and a `lat` or `latitude` attribute - * @return {lonlat} - * @throws {InvalidCoordinateException} + * @return {lonlat.types.output} + * @throws {lonlat.types.InvalidCoordinateException} * @example * var lonlat = require('@conveyal/lonlat') @@ -113,8 +113,8 @@ module.exports.fromLatlng = module.exports.fromLeaflet = function fromLatlng (lo * @memberof conveyal/lonlat * @param {Object} point An object with a `x` attribute representing `longitude` * and a `y` attribute representing `latitude` - * @return {lonlat} - * @throws {InvalidCoordinateException} + * @return {lonlat.types.output} + * @throws {lonlat.types.InvalidCoordinateException} * @example * var lonlat = require('@conveyal/lonlat') @@ -129,17 +129,21 @@ module.exports.fromPoint = fromPoint * Tries to parse from a string. * * @memberof conveyal/lonlat - * @param {string} str A string in the format: `longitude,latitude` - * @return {lonlat} - * @throws {InvalidCoordinateException} + * @param {string} str A string in the format: `longitude,latitude` + * @param {boolean} [latIsFirst=false] Whether or not the first value is 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.fromString('12,34') // { lon: 12, lat: 34 } + var position = lonlat.fromString('12,34', true) // { lon: 34, lat: 12 } */ -function fromString (str) { +function fromString (str, latIsFirst) { var arr = str.split(',') - return floatize({lon: arr[0], lat: arr[1]}) + return latIsFirst + ? floatize({lat: arr[0], lon: arr[1]}) + : floatize({lon: arr[0], lat: arr[1]}) } module.exports.fromString = fromString @@ -148,9 +152,9 @@ module.exports.fromString = fromString * * @param {input} lonlat1 * @param {input} lonlat2 - * @param {number} [epsilon] The maximum acceptable deviation to be considered equal. Default = 0 + * @param {number} [epsilon=0] The maximum acceptable deviation to be considered equal. * @return {boolean} - * @throws {InvalidCoordinateException} + * @throws {lonlat.types.InvalidCoordinateException} * @example * var lonlat = require('@conveyal/lonlat') @@ -165,10 +169,10 @@ module.exports.isEqual = function (lonlat1, lonlat2, epsilon) { /** * @param {input} input - * @param {number} [fixed] The number of decimal places to round to. - * @return {string} A string with in the format `longitude,latitude` rounded to + * @param {number} [fixed=5] The number of decimal places to round to. + * @return {string} A string with in the format `longitude,latitude` rounded to * the number of decimal places as specified by `fixed` - * @throws {InvalidCoordinateException} + * @throws {lonlat.types.InvalidCoordinateException} * @example * var lonlat = require('@conveyal/lonlat') @@ -184,9 +188,9 @@ module.exports.print = function print (input, fixed) { * * Translates to a coordinate array. * - * @param {input} input + * @param {lonlat.types.input} input * @return {Array} An array in the format [longitude, latitude] - * @throws {InvalidCoordinateException} + * @throws {lonlat.types.InvalidCoordinateException} * @example * var lonlat = require('@conveyal/lonlat') @@ -201,9 +205,9 @@ module.exports.toCoordinates = module.exports.toGeoJSON = function toCoordinates * Translates to {@link http://leafletjs.com/reference-1.0.3.html#latlng|Leaflet LatLng} object. * This function requires Leaflet to be installed as a global variable `L` in the window environment. * - * @param {input} input + * @param {lonlat.types.input} input * @return {Object} A Leaflet LatLng object - * @throws {InvalidCoordinateException} + * @throws {lonlat.types.InvalidCoordinateException} * @example * var lonlat = require('@conveyal/lonlat') @@ -218,9 +222,9 @@ module.exports.toLeaflet = function toLeaflet (input) { /** * Translates to point Object. * - * @param {input} input + * @param {lonlat.types.input} input * @return {Object} An object with `x` and `y` attributes representing latitude and longitude respectively - * @throws {InvalidCoordinateException} + * @throws {lonlat.types.InvalidCoordinateException} * @example * var lonlat = require('@conveyal/lonlat') @@ -234,9 +238,9 @@ module.exports.toPoint = function toPoint (input) { /** * Translates to coordinate string. * - * @param {input} input + * @param {lonlat.types.input} input * @return {string} A string in the format 'longitude,latitude' - * @throws {InvalidCoordinateException} + * @throws {lonlat.types.InvalidCoordinateException} * @example * var lonlat = require('@conveyal/lonlat') diff --git a/index.test.js b/index.test.js index 52428fc..d6444de 100644 --- a/index.test.js +++ b/index.test.js @@ -8,6 +8,7 @@ const lonlat = {lon, lat} const point = {x: lon, y: lat} const coordinates = [lon, lat] const str = `${lon},${lat}` +const strLatFirst = `${lat},${lon}` const latlng = {lat, lng: lon} describe('lonlat', () => { @@ -92,7 +93,10 @@ describe('lonlat', () => { description: 'Object with x and y keys' }, { calculated: ll.fromString(str), - description: 'String with comma separating lon and lat' + description: 'String with comma separating lon and lat, respectively' + }, { + calculated: ll.fromString(strLatFirst, true), + description: 'String with comma separating lat and lon, respectively' }] testCases.forEach((test) => {