Decode/Encode angles expressed as degrees, minutes, and seconds. This module defines several constants:
- hemisphere indicator (returned by
Decode) and a formatting
indicator (used by
Encode)
- 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 in
Encode
- DEGREE = 0;
- MINUTE = 1;
- SECOND = 2.
- Source:
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; thus
S3-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. Thus
7.0E1 is illegal, while 7.0E+1 is parsed as
(7.0E) + (+1), yielding the same result as
8.0E.
Parameters:
| Name | Type | Description |
|---|---|---|
dms |
string | the string. |
- Source:
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:
| Name | Type | Description |
|---|---|---|
angstr |
string | the string (this must not include a hemisphere indicator). |
- Source:
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:
| Name | Type | Description |
|---|---|---|
azistr |
string | the string (this may include an E/W hemisphere indicator). |
- Source:
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:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
stra |
string | the first string. |
||
strb |
string | the first string. |
||
longfirst |
bool |
<optional> |
false | if true assume then longitude is given first (in the absence of any hemisphere indicators). |
- Source:
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:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
angle |
number | input angle (degrees). |
||
trailing |
number | one of DEGREE, MINUTE, or SECOND to indicate the trailing component of the string (this component is given as a decimal number if necessary). |
||
prec |
number | the number of digits after the decimal point for the trailing component. |
||
ind |
number |
<optional> |
NONE | a formatting indicator, one of NONE, LATITUDE, LONGITUDE, AZIMUTH. |
dmssep |
char |
<optional> |
NULL | if non-null, use as the DMS separator character. |
- Source:
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