latlon-formatter

A set of functions to format latitude and longitude angles.

Installation

npm install latlon-formatter --save

Usage

• ES6:

  import { formatLatitude, formatLongitude } from 'latlon-formatter';
  const latitude = formatLatitude(Math.PI / 3); // => 60° 00′ 00″ N 
  const longitude = formatLongitude(-33.4, {
      degrees: true
  });   // => 034° 24′ 00″ W 

• require with Node.js:

  var formatter = require('latlon-formatter');
  var latitude = formatter.latitude(Math.PI / 3); // => 60° 00′ 00″ N 
  var longitude = formatter.longitude(-33.4, {
      degrees: true
  });   // => 034° 24′ 00″ W

• in browser include dist/latlon-formatter.js or dist/latlon-formatter.min.js script:

  var formatter = window.latlonFormatter;
  var latitude = formatter.latitude(Math.PI / 3); // => 60° 00′ 00″ N 
  var longitude = formatter.longitude(-33.4, {
      degrees: true
  });   // => 034° 24′ 00″ W

Methods

• latitude or formatLatitude — format latitude angle.

  Arguments:

  • value — angle's value;
  • options:
    • template — custom template (optional, default — {degree}° {prime}′ {doublePrime}″ {direction});
    • degrees — specifies whether value is in degrees or in radians (optional, default — false);
    • fixedCount — count of precision digits (optional, default — null leaving precision as is).

  Examples:

  formatter.latitude(33.4); // => 34° 24′ 00″ N

  formatter.latitude(-14.75, { degrees: true }); // => 14° 45′ 00″ S

  formatter.latitude(-14.75, {
      template: '{negativeSign}{value}°',
      degrees: true,
      fixedCount: 1
  }); // => —14.8°

• longitude or formatLongitude — format longitude angle.

  Arguments:

  • value — angle's value;
  • options:
    • template — custom template (optional, default — {degree}° {prime}′ {doublePrime}″ {direction});
    • degrees — specifies whether value is in degrees or in radians (optional, default — false);
    • fixedCount — count of precision digits (optional, default — null leaving precision as is).

  Examples:

  formatter.longitude(33.4); // => 034° 24′ 00″ E

  formatter.longitude(-14.75, { degrees: true }); // => 014° 45′ 00″ W

  formatter.longitude(-14.75, {
      template: '{negativeSign}{value}°',
      degrees: true,
      fixedCount: 1
  }); // => —14.8°

• angle or formatAngle — format any custom angle.

  Arguments:

  • value — angle's value;
  • options:
    • template — custom template (optional, default — {negativeSign}{value}°);
    • degrees — specifies whether value is in degrees or in radians (optional, default — false);
    • fixedCount — count of precision digits (optional, default — null leaving precision as is);
    • customTokens — an object or a function returning an object of additional custom tokens used in template.

  Examples:

  formatter.angle(3.4, {
      template: '{degree}° {prime}′ {doublePrime}″ {direction}',
      customTokens: f => {
          return {
              degree: (f.degrees < 10 ? '0' : '') + f.degree,
              direction: f.sign >= 0 ? 'N' : 'S'
          };
      }
  }); // => 03° 24′ 00″ N

Template tokens

All three format methods (latitude, longitude and angle) have the following predefined template tokens:

• value — angle's absolute value with optional precision specified by fixedCount option;
• degree — absolute (two-digits and three-digits for latitude and longitude respectively) degree value;
• prime — absolute two-digits prime value;
• doublePrime — absolute two-digits double prime value;
• sign — value's sign:
  • + — positive value;
  • — — negative value;
  • empty — zero value;
• negativeSign — the same as sign except that it's empty for both zero and positive values.

latitude and longitude methods additionally have direction token:

• N — non-negative latitude;
• S — negative latitude;
• E — non-negative longitude;
• W — negative longitude.

Any custom additional tokens can be specified by customTokens option of angle method.

Building

In order to build library run:

npm run build

Testing

Run unit tests:

npm test

Run tests with coverage:

npm run test:coverage

In order to run tests with Coveralls locally you have to provide COVERALLS_REPO_TOKEN:

COVERALLS_REPO_TOKEN=<token> npm run test:coveralls

Contributing

Before making a pull request, please, be sure that you start from develop branch.

License

MIT