GeographicLib: GeographicLib::DMS Class Reference (original) (raw)

Convert between degrees and the DMS representation. More...

#include <[GeographicLib/DMS.hpp](DMS%5F8hpp%5Fsource.html)>

Convert between degrees and the DMS representation.

Parse a string representing degree, minutes, and seconds and return the angle in degrees and format an angle in degrees as degree, minutes, and seconds. In addition, handle NANs and infinities on input and output.

Example of use:

#include

#include

#include

using namespace std;

try {

{

string dms = "30d14'45.6\"S";

DMS::flag type;

double ang = DMS::Decode(dms, type);

cout << type << " " << ang << "\n";

}

{

double ang = -30.245715;

string dms = DMS::Encode(ang, 6, DMS::LATITUDE);

cout << dms << "\n";

}

}

catch (const exception& e) {

cerr << "Caught exception: " << e.what() << "\n";

return 1;

}

}

int main(int argc, const char *const argv[])

Header for GeographicLib::DMS class.

Namespace for GeographicLib.

Definition at line 28 of file DMS.hpp.

◆ flag

Indicator for presence of hemisphere indicator (N/S/E/W) on latitudes and longitudes.

Definition at line 35 of file DMS.hpp.

◆ component

Indicator for trailing units on an angle.

Definition at line 67 of file DMS.hpp.

◆ Decode() [1/2]

Convert a string in DMS to an angle.

Parameters

Exceptions

Returns

angle (degrees).

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.

Note

At present, all the string handling in the C++ implementation of GeographicLib is with 8-bit characters. The support for unicode symbols for degrees, minutes, and seconds is therefore via the UTF-8 encoding. (The JavaScript implementation of this class uses unicode natively, of course.)

Here is the list of Unicode symbols supported for degrees, minutes, seconds, and the plus and minus signs; various symbols denoting variants of a space, which may separate the components of a DMS string, are removed:

• degrees:
  • d, D lower and upper case letters
  • U+00b0 degree symbol (°)
  • U+00ba masculine ordinal indicator (º)
  • U+2070 superscript zero (⁰)
  • U+02da ring above (˚)
  • U+2218 compose function (∘)
  • * the GRiD symbol for degrees
• minutes:
  • ' apostrophe
  • ‘ grave accent
  • U+2032 prime (′)
  • U+2035 back prime (‵)
  • U+00b4 acute accent (´)
  • U+2018 left single quote (‘)
  • U+2019 right single quote (’)
  • U+201b reversed-9 single quote (‛)
  • U+02b9 modifier letter prime (ʹ)
  • U+02ca modifier letter acute accent (ˊ)
  • U+02cb modifier letter grave accent (ˋ)
• seconds:
  • " quotation mark
  • U+2033 double prime (″)
  • U+2036 reversed double prime (‶)
  • U+02dd double acute accent (˝)
  • U+201c left double quote (“)
  • U+201d right double quote (”)
  • U+201f reversed-9 double quote (‟)
  • U+02ba modifier letter double prime (ʺ)
  • ’ ' any two consecutive symbols for minutes
• plus sign:
  • + plus
  • U+2795 heavy plus (➕)
  • U+2064 invisible plus (|⁤|)
• minus sign:
  • - hyphen
  • U+2010 dash (‐)
  • U+2011 non-breaking hyphen (‑)
  • U+2013 en dash (–)
  • U+2014 em dash (—)
  • U+2212 minus sign (−)
  • U+2796 heavy minus (➖)
• ignored spaces:
  • U+00a0 non-breaking space
  • U+2007 figure space (| |)
  • U+2009 thin space (| |)
  • U+200a hair space ( | |)
  • U+200b invisible space (|​|)
  • U+202f narrow space ( | |)
  • U+2063 invisible separator (|⁣|)

The codes with a leading zero byte, e.g., U+00b0, are accepted in their UTF-8 coded form 0xc2 0xb0 and as a single byte 0xb0.

Definition at line 35 of file DMS.cpp.

References GeographicLib::Utility::lookup(), and NONE.

Referenced by DecodeAngle(), DecodeAzimuth(), and DecodeLatLon().

◆ Decode() [2/2]

Convert DMS to an angle.

Parameters

Returns

angle (degrees)

This does not propagate the sign on d to the other components, so -3d20' would need to be represented as - DMS::Decode(3.0, 20.0) or DMS::Decode(-3.0, -20.0).

Definition at line 244 of file DMS.hpp.

◆ DecodeLatLon()

Convert a pair of strings to latitude and longitude.

Parameters

Exceptions

By default, the lat (resp., lon) is assigned to the results of decoding dmsa (resp., dmsb). However this is overridden if either dmsa or dmsb contain a latitude or longitude hemisphere designator (N, S, E, W). If an exception is thrown, lat and lon are unchanged.

Definition at line 363 of file DMS.cpp.

References Decode(), LATITUDE, LONGITUDE, NONE, GeographicLib::Math::qd, and GeographicLib::Utility::str().

Referenced by main(), and GeographicLib::GeoCoords::Reset().

◆ DecodeAngle()

Convert a string to an angle in degrees.

Parameters

Exceptions

Returns

angle (degrees)

No hemisphere designator is allowed and no check is done on the range of the result.

Definition at line 393 of file DMS.cpp.

References Decode(), and NONE.

◆ DecodeAzimuth()

Convert a string to an azimuth in degrees.

Parameters

Exceptions

Returns

azimuth (degrees) reduced to the range [−180°, 180°].

A hemisphere designator E/W can be used; the result is multiplied by −1 if W is present.

Definition at line 402 of file DMS.cpp.

References GeographicLib::Math::AngNormalize(), Decode(), and LATITUDE.

Referenced by main().

◆ Encode() [1/4]

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

Parameters

Exceptions

Returns

formatted string

The interpretation of ind is as follows:

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

The integer parts of the minutes and seconds components are always given with 2 digits.

Definition at line 411 of file DMS.cpp.

References GeographicLib::Math::AngNormalize(), AZIMUTH, DEGREE, GeographicLib::Math::dm, GeographicLib::Math::ds, GeographicLib::Math::extra_digits(), LATITUDE, MINUTE, GeographicLib::Math::ms, NONE, SECOND, GeographicLib::Utility::str(), and GeographicLib::Math::td.

Referenced by AzimuthString(), GeographicLib::GeoCoords::DMSRepresentation(), and LatLonString().

◆ Encode() [2/4]

Convert angle into a DMS string (using d, ', and ") selecting the trailing component based on the precision.

Parameters

Exceptions

Returns

formatted string

prec indicates the precision relative to 1 degree, e.g., prec = 3 gives a result accurate to 0.1' and prec = 4 gives a result accurate to 1". ind is interpreted as in DMS::Encode with the additional facility that DMS::NUMBER represents angle as a number in fixed format with precision prec.

Definition at line 350 of file DMS.hpp.

◆ Encode() [3/4]

Split angle into degrees and minutes

Parameters

Definition at line 366 of file DMS.hpp.

◆ Encode() [4/4]

Split angle into degrees and minutes and seconds.

Parameters

Definition at line 378 of file DMS.hpp.

The documentation for this class was generated from the following files:

• DMS.hpp
• DMS.cpp