NETGeographicLib::DMS Class Reference

.NET wrapper for GeographicLib::DMS. More...

#include <NETGeographicLib/DMS.h>

List of all members.

Public Types

enum  Flag {
  NONE, LATITUDE, LONGITUDE, AZIMUTH,
  NUMBER
}
enum  Component { DEGREE, MINUTE, SECOND }

Static Public Member Functions

static double Decode (System::String^ dms,[System::Runtime::InteropServices::Out] Flag% ind)
static double Decode (double d, double m, double s)
static void DecodeLatLon (System::String^ dmsa, System::String^ dmsb,[System::Runtime::InteropServices::Out] double% lat,[System::Runtime::InteropServices::Out] double% lon, bool swaplatlong)
static double DecodeAngle (System::String^ angstr)
static double DecodeAzimuth (System::String^ azistr)
static System::String^ Encode (double angle, Component trailing, unsigned prec, Flag ind, char dmssep)
static System::String^ Encode (double angle, unsigned prec, Flag ind, char dmssep)
static void Encode (double ang,[System::Runtime::InteropServices::Out] double% d,[System::Runtime::InteropServices::Out] double% m)
static void Encode (double ang,[System::Runtime::InteropServices::Out] double% d,[System::Runtime::InteropServices::Out] double% m,[System::Runtime::InteropServices::Out] double% s)

Detailed Description

.NET wrapper for GeographicLib::DMS.

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.

C# Example:

using System;
using NETGeographicLib;

namespace example_DMS
{
    class Program
    {
        static void Main(string[] args)
        {
            try {
            {
                string dms = "30d14'45.6\"S";
                DMS.Flag type;
                double ang = DMS.Decode(dms, out type);
                Console.WriteLine(String.Format("Type: {0} String: {1}", type, ang));
            }
            {
                double ang = -30.245715;
                string dms = DMS.Encode(ang, 6, DMS.Flag.LATITUDE, 0);
                Console.WriteLine(String.Format("Latitude: {0}", dms));
            }
            }
            catch (GeographicErr e) {
                Console.WriteLine( String.Format( "Caught exception: {0}", e.Message ) );
            }
        }
    }
}

Managed C++ Example:

using namespace System;
using namespace NETGeographicLib;

int main(array<System::String ^> ^/*args*/)
{
    try {
    {
        System::String^ dms = "30d14'45.6\"S";
        DMS::Flag type;
        double ang = DMS::Decode(dms, type);
        Console::WriteLine(String::Format("Type: {0} String: {1}", type, ang));
    }
    {
        double ang = -30.245715;
        System::String^ dms = DMS::Encode(ang, 6, DMS::Flag::LATITUDE, 0);
        Console::WriteLine(String::Format("Latitude: {0}", dms));
    }
    }
    catch (GeographicErr^ e) {
        Console::WriteLine( String::Format( "Caught exception: {0}", e->Message ) );
        return -1;
    }
    return 0;
}

Visual Basic Example:

Imports NETGeographicLib

Module example_DMS
    Sub Main()
        Try
            Dim desc As String = "30d14'45.6""S"
            Dim type As DMS.Flag
            Dim ang As Double = DMS.Decode(desc, type)
            Console.WriteLine(String.Format("Type: {0} String: {1}", type, ang))
            ang = -30.245715
            Dim prec As UInteger = 6
            desc = DMS.Encode(ang, prec, DMS.Flag.LATITUDE, 0)
            Console.WriteLine(String.Format("Latitude: {0}", desc))
        Catch ex As GeographicErr
            Console.WriteLine(String.Format("Caught exception: {0}", ex.Message))
        End Try
    End Sub
End Module

Definition at line 29 of file DMS.h.


Member Enumeration Documentation

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 36 of file DMS.h.

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 68 of file DMS.h.


Member Function Documentation

static double NETGeographicLib::DMS::Decode ( System::String^   dms,
[System::Runtime::InteropServices::Out] Flag%   ind 
) [static]

Convert a string in DMS to an angle.

Parameters:
[in] dms string input.
[out] ind a DMS::flag value signaling the presence of a hemisphere indicator.
Exceptions:
GeographicErr if 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. 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, -2030'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
  • ILLEGAL (the exception thrown explains the problem)
    • 4d5"4', 4::5, 4:5:, :4:5, 4d4.5'4", -N20.5, 1.8e2d, 4:60, 4d-5'

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:

  • 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

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.

static double NETGeographicLib::DMS::Decode ( double  d,
double  m,
double  s 
) [inline, static]

Convert DMS to an angle.

Parameters:
[in] d degrees.
[in] m arc minutes.
[in] s arc 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 169 of file DMS.h.

static void NETGeographicLib::DMS::DecodeLatLon ( System::String^   dmsa,
System::String^   dmsb,
[System::Runtime::InteropServices::Out] double%   lat,
[System::Runtime::InteropServices::Out] double%   lon,
bool  swaplatlong 
) [static]

Convert a pair of strings to latitude and longitude.

Parameters:
[in] dmsa first string.
[in] dmsb second string.
[out] lat latitude.
[out] lon longitude reduced to the range [180, 180).
[in] swaplatlong if true assume longitude is given before latitude in the absence of hemisphere designators (default false).
Exceptions:
GeographicErr if dmsa or dmsb is malformed.
GeographicErr if dmsa and dmsb are both interpreted as latitudes.
GeographicErr if dmsa and dmsb are both interpreted as longitudes.
GeographicErr if decoded latitude is not in [90, 90].
GeographicErr if decoded longitude is not in [540, 540).

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.

static double NETGeographicLib::DMS::DecodeAngle ( System::String^   angstr  )  [static]

Convert a string to an angle in degrees.

Parameters:
[in] angstr input string.
Exceptions:
GeographicErr if angstr is malformed.
GeographicErr if angstr includes a hemisphere designator.
Returns:
angle (degrees)

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

static double NETGeographicLib::DMS::DecodeAzimuth ( System::String^   azistr  )  [static]

Convert a string to an azimuth in degrees.

Parameters:
[in] azistr input string.
Exceptions:
GeographicErr if azistr is malformed.
GeographicErr if azistr includes a N/S designator.
GeographicErr if decoded azimuth is not in [540, 540).
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.

static System::String ^ NETGeographicLib::DMS::Encode ( double  angle,
Component  trailing,
unsigned  prec,
Flag  ind,
char  dmssep 
) [static]

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

Parameters:
[in] angle input angle (degrees)
[in] trailing DMS::component value indicating the trailing units on the string and this is given as a decimal number if necessary.
[in] prec the number of digits after the decimal point for the trailing component.
[in] ind DMS::flag value indicated additional formatting.
[in] dmssep if non-null, use as the DMS separator character (instead of d, ', " delimiters).
Exceptions:
GeographicErr if 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.

static System::String ^ NETGeographicLib::DMS::Encode ( double  angle,
unsigned  prec,
Flag  ind,
char  dmssep 
) [static]

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

Parameters:
[in] angle input angle (degrees)
[in] prec the precision relative to 1 degree.
[in] ind DMS::flag value indicated additional formatting.
[in] dmssep if non-null, use as the DMS separator character (instead of d, ', " delimiters).
Exceptions:
std::bad_alloc if 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.

static void NETGeographicLib::DMS::Encode ( double  ang,
[System::Runtime::InteropServices::Out] double%   d,
[System::Runtime::InteropServices::Out] double%   m 
) [inline, static]

Split angle into degrees and minutes

Parameters:
[in] ang angle (degrees)
[out] d degrees (an integer returned as a double)
[out] m arc minutes.

Definition at line 302 of file DMS.h.

static void NETGeographicLib::DMS::Encode ( double  ang,
[System::Runtime::InteropServices::Out] double%   d,
[System::Runtime::InteropServices::Out] double%   m,
[System::Runtime::InteropServices::Out] double%   s 
) [inline, static]

Split angle into degrees and minutes and seconds.

Parameters:
[in] ang angle (degrees)
[out] d degrees (an integer returned as a double)
[out] m arc minutes (an integer returned as a double)
[out] s arc seconds.

Definition at line 317 of file DMS.h.


The documentation for this class was generated from the following file:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends

Generated on 6 Oct 2014 for NETGeographicLib by  doxygen 1.6.1