JSDoc: Module: DMS (original) (raw)

Decode/Encode angles expressed as degrees, minutes, and seconds. This module defines several constants:

• hemisphere indicator (returned byDecode) and a formatting indicator (used byEncode)
  • NONE = 0, no designator and format as plain angle;
  • LATITUDE = 1, a N/S designator and format as latitude;
  • LONGITUDE = 2, an E/W designator and format as longitude;
  • AZIMUTH = 3, format as azimuth;
• the specification of the trailing component inEncode
  • DEGREE = 0;
  • MINUTE = 1;
  • SECOND = 2.

Source:

• geographiclib-dms/src/DMS.js, line 40

Example

var DMS = require("geographiclib-dms"),
    ang = DMS.Decode("127:54:3.123123W");
console.log("Azimuth " +
    DMS.Encode(ang.val, DMS.MINUTE, 7, ang.ind) +
    " = " + ang.val.toFixed(9));

Methods

(static) Decode(dms) → {object}

Decode a DMS string.

Convert a DMS string into an angle. Degrees, minutes, and seconds are indicated by the characters d, ' (single quote), " (double quote), and these components may only be given in this order. Any (but not all) components may be omitted and other symbols (e.g., the ° symbol for degrees and the unicode prime and double prime symbols for minutes and seconds) may be substituted; two single quotes can be used instead of ". The last component indicator may be omitted and is assumed to be the next smallest unit (thus 33d10 is interpreted as 33d10'). The final component may be a decimal fraction but the non-final components must be integers. Instead of using d, ', and " to indicate degrees, minutes, and seconds, : (colon) may be used to separate these components (numbers must appear before and after each colon); thus 50d30'10.3" may be written as 50:30:10.3, 5.5' may be written 0:5.5, and so on. The integer parts of the minutes and seconds components must be less than 60. A single leading sign is permitted. A hemisphere designator (N, E, W, S) may be added to the beginning or end of the string. The result is multiplied by the implied sign of the hemisphere designator (negative for S and W). In addition ind is set to DMS.LATITUDE if N or S is present, to DMS.LONGITUDE if E or W is present, and to DMS.NONE otherwise. Leading and trailing whitespace is removed from the string before processing. This routine throws an error on a malformed string. No check is performed on the range of the result. Examples of legal and illegal strings are

• LEGAL (all the entries on each line are equivalent)
  • -20.51125, 20d30'40.5"S, -20°30'40.5, -20d30.675, N-20d30'40.5", -20:30:40.5
  • 4d0'9, 4d9", 4d9'', 4:0:9, 004:00:09, 4.0025, 4.0025d, 4d0.15, 04:.15
  • 4:59.99999999999999, 4:60.0, 4:59:59.9999999999999, 4:59:60.0, 5
• ILLEGAL (the exception thrown explains the problem)
  • 4d5"4', 4::5, 4:5:, :4:5, 4d4.5'4", -N20.5, 1.8e2d, 4:60, 4:59:60

The decoding operation can also perform addition and subtraction operations. If the string includes internal signs (i.e., not at the beginning nor immediately after an initial hemisphere designator), then the string is split immediately before such signs and each piece is decoded according to the above rules and the results added; thusS3-2.5+4.1N is parsed as the sum of S3,-2.5, +4.1N. Any piece can include a hemisphere designator; however, if multiple designators are given, they must compatible; e.g., you cannot mix N and E. In addition, the designator can appear at the beginning or end of the first piece, but must be at the end of all subsequent pieces (a hemisphere designator is not allowed after the initial sign). Examples of legal and illegal combinations are

• LEGAL (these are all equivalent)
  • -070:00:45, 70:01:15W+0:0.5, 70:01:15W-0:0:30W, W70:01:15+0:0:30E
• ILLEGAL (the exception thrown explains the problem)
  • 70:01:15W+0:0:15N, W70:01:15+W0:0:15

WARNING The "exponential" notation is not recognized. Thus7.0E1 is illegal, while 7.0E+1 is parsed as(7.0E) + (+1), yielding the same result as8.0E.

Parameters:

Source:

• geographiclib-dms/src/DMS.js, line 131

Throws:

an error if the string is illegal.

Returns:

r where r.val is the decoded value (degrees) and r.ind is a hemisphere designator, one of NONE, LATITUDE, LONGITUDE.

Type

object

(static) DecodeAngle(angstr) → {number}

Decode a DMS string interpreting it as an arc length.

Parameters:

Source:

• geographiclib-dms/src/DMS.js, line 453

Throws:

an error if the string is illegal.

Returns:

the arc length (degrees).

Type

number

(static) DecodeAzimuth(azistr) → {number}

Decode a DMS string interpreting it as an azimuth.

Parameters:

Source:

• geographiclib-dms/src/DMS.js, line 469

Throws:

an error if the string is illegal.

Returns:

the azimuth (degrees).

Type

number

(static) DecodeLatLon(stra, strb, longfirstopt) → {object}

Decode two DMS strings interpreting them as a latitude/longitude pair.

Parameters:

Source:

• geographiclib-dms/src/DMS.js, line 418

Throws:

an error if the strings are illegal.

Returns:

r where r.lat is the decoded latitude and r.lon is the decoded longitude (both in degrees).

Type

object

(static) Encode(angle, trailing, prec, indopt, dmssepopt) → {string}

Convert angle (in degrees) into a DMS string (using °, ', and ").

Parameters:

Source:

• geographiclib-dms/src/DMS.js, line 508

Returns:

the resulting string formatted as follows:

• NONE, signed result no leading zeros on degrees except in the units place, e.g., -8°03'.
• LATITUDE, trailing N or S hemisphere designator, no sign, pad degrees to 2 digits, e.g., 08°03'S.
• LONGITUDE, trailing E or W hemisphere designator, no sign, pad degrees to 3 digits, e.g., 008°03'W.
• AZIMUTH, convert to the range [0, 360°), no sign, pad degrees to 3 digits, e.g., 351°57'.

WARNING Because of implementation of JavaScript's toFixed function, this routine rounds ties away from zero. This is different from the C++ version of GeographicLib which implements the "round ties to even" rule.

WARNING Angles whose magnitude is equal to or greater than 1021 are printed as a plain number in exponential notation, e.g., "1e21".

Type

string