Public Types | Static Public Member Functions | Private Types | Private Member Functions | Static Private Member Functions | Static Private Attributes | List of all members
GeographicLib::DMS Class Reference

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

#include <DMS.hpp>

Public Types

enum  component { DEGREE, MINUTE, SECOND }
 
enum  flag {
  NONE, LATITUDE, LONGITUDE, AZIMUTH,
  NUMBER
}
 

Static Public Member Functions

static Math::real Decode (const std::string &dms, flag &ind)
 
static Math::real Decode (real d, real m=0, real s=0)
 
static Math::real DecodeAngle (const std::string &angstr)
 
static Math::real DecodeAzimuth (const std::string &azistr)
 
static void DecodeLatLon (const std::string &dmsa, const std::string &dmsb, real &lat, real &lon, bool longfirst=false)
 
static std::string Encode (real angle, component trailing, unsigned prec, flag ind=NONE, char dmssep=char(0))
 
static std::string Encode (real angle, unsigned prec, flag ind=NONE, char dmssep=char(0))
 
static void Encode (real ang, real &d, real &m)
 
static void Encode (real ang, real &d, real &m, real &s)
 

Private Types

typedef Math::real real
 

Private Member Functions

 DMS ()
 

Static Private Member Functions

static Math::real InternalDecode (const std::string &dmsa, flag &ind)
 
static Math::real NumMatch (const std::string &s)
 
static void replace (std::string &s, const std::string &pat, char c)
 

Static Private Attributes

static const char *const components_ [3] = {"degrees", "minutes", "seconds"}
 
static const char *const digits_ = "0123456789"
 
static const char *const dmsindicators_ = "D'\":"
 
static const char *const hemispheres_ = "SNWE"
 
static const char *const signs_ = "-+"
 

Detailed Description

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:

// Example of using the GeographicLib::DMS class
#include <iostream>
#include <string>
#include <exception>
using namespace std;
using namespace GeographicLib;
int main() {
try {
{
string dms = "30d14'45.6\"S";
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;
}
}

Definition at line 34 of file DMS.hpp.

Member Typedef Documentation

◆ real

Definition at line 92 of file DMS.hpp.

Member Enumeration Documentation

◆ component

Indicator for trailing units on an angle.

Enumerator
DEGREE 

Trailing unit is degrees.

MINUTE 

Trailing unit is arc minutes.

SECOND 

Trailing unit is arc seconds.

Definition at line 73 of file DMS.hpp.

◆ flag

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

Enumerator
NONE 

No indicator present.

LATITUDE 

Latitude indicator (N/S) present.

LONGITUDE 

Longitude indicator (E/W) present.

AZIMUTH 

Used in Encode to indicate output of an azimuth in [000, 360) with no letter indicator.

NUMBER 

Used in Encode to indicate output of a plain number.

Definition at line 41 of file DMS.hpp.

Constructor & Destructor Documentation

◆ DMS()

GeographicLib::DMS::DMS ( )
private

Member Function Documentation

◆ Decode() [1/2]

Math::real GeographicLib::DMS::Decode ( const std::string &  dms,
flag ind 
)
static

Convert a string in DMS to an angle.

Parameters
[in]dmsstring input.
[out]inda DMS::flag value signaling the presence of a hemisphere indicator.
Exceptions
GeographicErrif dms is malformed (see below).
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. 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 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 sign:

  • 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
  • minutes:
    • ' apostrophe
    • U+2032 prime (′)
    • U+00b4 acute accent
    • U+2019 right single quote (’)
  • seconds:
    • " quotation mark
    • U+2033 double prime (″)
    • U+201d right double quote (”)
    • ' ' any two consecutive symbols for minutes
  • leading sign:
    • U+2212 minus sign (−)

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 28 of file src/DMS.cpp.

◆ Decode() [2/2]

static Math::real GeographicLib::DMS::Decode ( real  d,
real  m = 0,
real  s = 0 
)
inlinestatic

Convert DMS to an angle.

Parameters
[in]ddegrees.
[in]marc minutes.
[in]sarc seconds.
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 223 of file DMS.hpp.

◆ DecodeAngle()

Math::real GeographicLib::DMS::DecodeAngle ( const std::string &  angstr)
static

Convert a string to an angle in degrees.

Parameters
[in]angstrinput string.
Exceptions
GeographicErrif angstr is malformed.
GeographicErrif angstr includes a hemisphere designator.
Returns
angle (degrees)

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

Definition at line 281 of file src/DMS.cpp.

◆ DecodeAzimuth()

Math::real GeographicLib::DMS::DecodeAzimuth ( const std::string &  azistr)
static

Convert a string to an azimuth in degrees.

Parameters
[in]azistrinput string.
Exceptions
GeographicErrif azistr is malformed.
GeographicErrif azistr includes a N/S designator.
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 290 of file src/DMS.cpp.

◆ DecodeLatLon()

void GeographicLib::DMS::DecodeLatLon ( const std::string &  dmsa,
const std::string &  dmsb,
real lat,
real lon,
bool  longfirst = false 
)
static

Convert a pair of strings to latitude and longitude.

Parameters
[in]dmsafirst string.
[in]dmsbsecond string.
[out]latlatitude (degrees).
[out]lonlongitude (degrees).
[in]longfirstif true assume longitude is given before latitude in the absence of hemisphere designators (default false).
Exceptions
GeographicErrif dmsa or dmsb is malformed.
GeographicErrif dmsa and dmsb are both interpreted as latitudes.
GeographicErrif dmsa and dmsb are both interpreted as longitudes.
GeographicErrif decoded latitude is not in [−90°, 90°].

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 252 of file src/DMS.cpp.

◆ Encode() [1/4]

string GeographicLib::DMS::Encode ( real  angle,
component  trailing,
unsigned  prec,
flag  ind = NONE,
char  dmssep = char(0) 
)
static

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

Parameters
[in]angleinput angle (degrees)
[in]trailingDMS::component value indicating the trailing units of the string (this component is given as a decimal number if necessary).
[in]precthe number of digits after the decimal point for the trailing component.
[in]indDMS::flag value indicating additional formatting.
[in]dmssepif non-null, use as the DMS separator character (instead of d, ', " delimiters).
Exceptions
std::bad_allocif memory for the string can't be allocated.
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 299 of file src/DMS.cpp.

◆ Encode() [2/4]

static std::string GeographicLib::DMS::Encode ( real  angle,
unsigned  prec,
flag  ind = NONE,
char  dmssep = char(0) 
)
inlinestatic

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

Parameters
[in]angleinput angle (degrees)
[in]precthe precision relative to 1 degree.
[in]indDMS::flag value indicated additional formatting.
[in]dmssepif non-null, use as the DMS separator character (instead of d, ', " delimiters).
Exceptions
std::bad_allocif memory for the string can't be allocated.
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 329 of file DMS.hpp.

◆ Encode() [3/4]

static void GeographicLib::DMS::Encode ( real  ang,
real d,
real m 
)
inlinestatic

Split angle into degrees and minutes

Parameters
[in]angangle (degrees)
[out]ddegrees (an integer returned as a real)
[out]marc minutes.

Definition at line 345 of file DMS.hpp.

◆ Encode() [4/4]

static void GeographicLib::DMS::Encode ( real  ang,
real d,
real m,
real s 
)
inlinestatic

Split angle into degrees and minutes and seconds.

Parameters
[in]angangle (degrees)
[out]ddegrees (an integer returned as a real)
[out]marc minutes (an integer returned as a real)
[out]sarc seconds.

Definition at line 357 of file DMS.hpp.

◆ InternalDecode()

Math::real GeographicLib::DMS::InternalDecode ( const std::string &  dmsa,
flag ind 
)
staticprivate

Definition at line 81 of file src/DMS.cpp.

◆ NumMatch()

static Math::real GeographicLib::DMS::NumMatch ( const std::string &  s)
staticprivate

◆ replace()

static void GeographicLib::DMS::replace ( std::string &  s,
const std::string &  pat,
char  c 
)
inlinestaticprivate

Definition at line 94 of file DMS.hpp.

Member Data Documentation

◆ components_

const char *const GeographicLib::DMS::components_ = {"degrees", "minutes", "seconds"}
staticprivate

Definition at line 107 of file DMS.hpp.

◆ digits_

const char *const GeographicLib::DMS::digits_ = "0123456789"
staticprivate

Definition at line 105 of file DMS.hpp.

◆ dmsindicators_

const char *const GeographicLib::DMS::dmsindicators_ = "D'\":"
staticprivate

Definition at line 106 of file DMS.hpp.

◆ hemispheres_

const char *const GeographicLib::DMS::hemispheres_ = "SNWE"
staticprivate

Definition at line 103 of file DMS.hpp.

◆ signs_

const char *const GeographicLib::DMS::signs_ = "-+"
staticprivate

Definition at line 104 of file DMS.hpp.


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


gtsam
Author(s):
autogenerated on Tue Jul 4 2023 02:46:12