An accurate representation of angles. More...

#include <GeographicLib/Angle.hpp>

Public Member Functions
Inspector functions.
T	s () const
T	c () const
T	t () const
T	n () const
T	n0 () const
Converting AngleT into other representations
	operator T () const
T	degrees () const
T	degrees0 () const
T	radians () const
T	radians0 () const
T	lam () const
AngleT	nearest (unsigned ind=0U) const
T	ncardinal () const
unsigned	quadrant () const
Elementary arithmetic operations on AngleT
AngleT	operator- () const
AngleT &	operator+= (const AngleT &p)
AngleT &	operator-= (const AngleT &p)
AngleT	operator+ (const AngleT &p) const
AngleT	operator- (const AngleT &p) const
bool	zerop (T mult=0) const
bool	operator== (const AngleT &p) const
Operations which modify a AngleT
AngleT &	round ()
AngleT &	renormalize ()
AngleT &	setn (T n=0)
AngleT &	setn0 (T n=0)
AngleT &	setquadrant (unsigned q)
AngleT &	reflect (bool flips, bool flipc=false, bool swapp=false)
Operations which return a new AngleT
AngleT	base () const
AngleT	rebase (const AngleT &c) const
AngleT	flipsign (T mult) const
AngleT	modang (T m) const

Static Public Member Functions
Converting AngleT to and from a string representation
static void	DecodeLatLon (const std::string &stra, const std::string &strb, AngleT &lat, AngleT &lon, bool longfirst=false)
static AngleT	DecodeAzimuth (const std::string &azistr)
static std::string	LatLonString (AngleT lat, AngleT lon, int prec, bool dms=false, char dmssep='\0', bool longfirst=false)
static std::string	AzimuthString (AngleT azi, int prec, bool dms=false, char dmssep='\0')

Creating AngleT objects.
	AngleT ()
	AngleT (T s, T c, T num=0, bool normp=false)
	AngleT (T deg)
static AngleT	degrees (T deg)
static AngleT	radians (T rad)
static AngleT	lam (T q)
static AngleT	NaN ()
static AngleT	cardinal (T q)
static AngleT	eps ()

Detailed Description

template<typename T = Math::real>
class GeographicLib::AngleT< T >

An accurate representation of angles.

Template Parameters

T	the working floating point type.

This class provides an accurate representation of angle via 3 numbers, its sine = s and cosine = c, and the number of turns = n. The angle is then 2n π + atan2(s, c). This representation offers several advantages:

the cardinal directors (multiples of 90°) are exactly represented (a benefit shared by representing angles as degrees);
angles very close to any cardinal direction are accurately represented;
there's no loss of precision with large angles (outside the "normal" range [−180°, +180°]);
various operations, such as adding a multiple of 90° to an angle are performed exactly.

This representation does not favor degrees over radians. However, the one-argument constructor, AngleT(T), does the conversion from degrees and the cast to T, AngleT::operator T(), returns the angle in degrees. There are alternatives, radians(T) and radians() const, to allow these conversions with radians.

N.B. n is stored as a real. This allows it to be inf or nan.

Example of use:

// Example of using the GeographicLib::Angle class.
 
#include <iostream>
#include <iomanip>
#include <exception>
#include <GeographicLib/Angle.hpp>
 
int main(int argc, const char* const argv[]) {
  try {
    using ang = GeographicLib::Angle;
    // Print table of parametric latitudes for f = 0.5
    double f = 0.5;
    std::cout << std::fixed << std::setprecision(4);
    for (double d = 0; d <= 90; d+=10) {
      ang phi{d};
      std::cout << double(d) << " " << double(phi.modang(1-f)) << "\n";
    }
  }
  catch (const std::exception& e) {
    std::cerr << "Caught exception: " << e.what() << "\n";
    return 1;
  }
}

Definition at line 50 of file Angle.hpp.

Constructor & Destructor Documentation

◆ AngleT() [1/3]

template<typename T = Math::real>

GeographicLib::AngleT< T >::AngleT ( )

inline

The default constructor.

This sets the angle to 0.

Definition at line 65 of file Angle.hpp.

Referenced by AzimuthString(), base(), cardinal(), DecodeAzimuth(), DecodeLatLon(), degrees(), eps(), flipsign(), lam(), LatLonString(), modang(), NaN(), nearest(), operator T(), operator+(), operator+=(), operator-(), operator-(), operator-=(), operator==(), radians(), rebase(), reflect(), renormalize(), round(), setn(), setn0(), and setquadrant().

◆ AngleT() [2/3]

template<typename T>

GeographicLib::AngleT< T >::AngleT	(	T	s,
		T	c,
		T	num = 0,
		bool	normp = false )

inline

The general constructor.

Parameters

[in]	s	the sine component.
[in]	c	the cosine component.
[in]	num	the number of turns (default 0).
[in]	normp	are s and c normalized (default false).

Warning: either s or c can be infinite, but not both.

By default, the point (s, c) is scaled to lie on the unit circle. Setting normp = true skips this step; in this case (s, c) should already lie on the unit circle.

Definition at line 472 of file Angle.hpp.

References c(), GeographicLib::Math::NaN(), and s().

◆ AngleT() [3/3]

template<typename T>

GeographicLib::AngleT< T >::AngleT ( T deg )

inlineexplicit

The 1-argument constructor.

Parameters

[in] deg the angle in degrees.

Note: This is an explicit constructor to avoid accidental conversions.

Definition at line 505 of file Angle.hpp.

References GeographicLib::Math::atan2d(), GeographicLib::Math::sincosd(), and GeographicLib::Math::td.

Member Function Documentation

◆ degrees() [1/2]

template<typename T>

AngleT< T > GeographicLib::AngleT< T >::degrees ( T deg )

inlinestatic

The convert an angle in degrees to an AngleT.

Parameters

[in] deg the angle in degrees.

Returns: the AngleT.

Note: This mimics the behavior of AngleT(T deg);

Definition at line 519 of file Angle.hpp.

References AngleT().

◆ radians() [1/2]

template<typename T>

AngleT< T > GeographicLib::AngleT< T >::radians ( T rad )

inlinestatic

Convert an angle in radians to an AngleT.

Parameters

[in] rad the angle in radians.

Returns: the AngleT.

Note: This is the radians analog of degrees(T).

Definition at line 534 of file Angle.hpp.

References AngleT(), and GeographicLib::Math::pi().

Referenced by GeographicLib::Triaxial::Geodesic3::Inverse().

◆ lam() [1/2]

template<typename T>

AngleT< T > GeographicLib::AngleT< T >::lam ( T q )

inlinestatic

Convert an lambertian to an AngleT.

Parameters

[in] q the lambertian of the angle.

Returns: the AngleT.

This sets the angle to atan(sinh(q)).

Definition at line 555 of file Angle.hpp.

References AngleT().

◆ NaN()

template<typename T>

AngleT< T > GeographicLib::AngleT< T >::NaN ( )

inlinestatic

Not an angle.

Returns: the AngleT equivalent to not-a-number.

Definition at line 567 of file Angle.hpp.

References AngleT(), and GeographicLib::Math::NaN().

Referenced by cardinal(), and modang().

◆ cardinal()

template<typename T>

AngleT< T > GeographicLib::AngleT< T >::cardinal ( T q )

inlinestatic

A cardinal direction.

Parameters

[in] q the number of quarter turns.

Returns: the AngleT equivalent to q quarter turns.

q is rounded to an integer and q = ±0 are distinguished. NaN() is returned is q is not finite.

Definition at line 721 of file Angle.hpp.

References AngleT(), c(), NaN(), and s().

◆ eps()

template<typename T>

AngleT< T > GeographicLib::AngleT< T >::eps ( )

inlinestatic

Return a tiny angle.

Returns: a tiny angle.

This allows angles extremely close to the cardinal directions to be generated. The round() function will flush this angle to 0.

Definition at line 581 of file Angle.hpp.

References AngleT().

◆ s()

template<typename T = Math::real>

T GeographicLib::AngleT< T >::s ( ) const

inline

Returns: the sine of the angle.

Definition at line 149 of file Angle.hpp.

◆ c()

template<typename T = Math::real>

T GeographicLib::AngleT< T >::c ( ) const

inline

Returns: the cosine of the angle.

Definition at line 153 of file Angle.hpp.

◆ t()

template<typename T = Math::real>

T GeographicLib::AngleT< T >::t ( ) const

inline

Returns: the tangent of the angle.

Definition at line 157 of file Angle.hpp.

Referenced by lam(), operator+(), operator-(), operator==(), and rebase().

◆ n()

template<typename T = Math::real>

T GeographicLib::AngleT< T >::n ( ) const

inline

Returns: the number of turns.

Definition at line 161 of file Angle.hpp.

Referenced by main(), setn(), setn0(), GeographicLib::Triaxial::Conformal3::x(), and GeographicLib::Triaxial::Conformal3::y().

◆ n0()

template<typename T>

T GeographicLib::AngleT< T >::n0 ( ) const

inline

Returns: the number of turns treating −180° as +180° less 1 turn.

Definition at line 669 of file Angle.hpp.

Referenced by rebase().

◆ operator T()

template<typename T>

GeographicLib::AngleT< T >::operator T ( ) const

inlineexplicit

Convert an AngleT to degrees via a type conversion.

Returns: the angle in degrees.

Note: This is an explicit type conversion to avoid accidental conversions.

Definition at line 512 of file Angle.hpp.

References AngleT(), degrees0(), and GeographicLib::Math::td.

◆ degrees() [2/2]

template<typename T>

T GeographicLib::AngleT< T >::degrees ( ) const

inline

Convert an AngleT to degrees.

Returns: the angle in degrees.

Note: This mimics the behavior of AngleT::operator T().

Definition at line 524 of file Angle.hpp.

◆ degrees0()

template<typename T>

T GeographicLib::AngleT< T >::degrees0 ( ) const

inline

Convert an AngleT to degrees ignoring the number of turns.

Returns: the angle in degrees assuming n() is zero.

Definition at line 529 of file Angle.hpp.

References GeographicLib::Math::atan2d().

Referenced by operator T().

◆ radians() [2/2]

template<typename T>

T GeographicLib::AngleT< T >::radians ( ) const

inline

Convert an AngleT to radians.

Returns: the angle in radians.

Note: This is the radians analog of degrees().

Definition at line 542 of file Angle.hpp.

References GeographicLib::Math::pi(), and radians0().

◆ radians0()

template<typename T>

T GeographicLib::AngleT< T >::radians0 ( ) const

inline

Convert an AngleT to radians ignoring the number of turns.

Returns: the angle in radians assuming n() is zero.

Note: This is the radians analog of degrees0().

Definition at line 549 of file Angle.hpp.

Referenced by GeographicLib::Triaxial::Geodesic3::Inverse(), and radians().

◆ lam() [2/2]

template<typename T>

T GeographicLib::AngleT< T >::lam ( ) const

inline

Return the lambertian of the AngleT.

Returns: the lambertian.

The lambertian of φ is asinh tan φ.

Definition at line 561 of file Angle.hpp.

References t().

◆ nearest()

template<typename T>

AngleT< T > GeographicLib::AngleT< T >::nearest ( unsigned ind = 0U ) const

inline

Return the nearest cardinal direction as an AngleT.

Parameters

[in] ind an indicator.

Returns: the nearest cardinal direction as an AngleT.

If ind == 0 (the default) the closest cardinal direction is returned. Otherwise, if ind is even, the closest even (N/S) cardinal direction is returned; or, if ind is odd, the closest odd (E/W) cardinal direction is returned.

Definition at line 743 of file Angle.hpp.

References AngleT(), c(), and s().

◆ ncardinal()

template<typename T>

T GeographicLib::AngleT< T >::ncardinal ( ) const

inline

Return the nearest cardinal direction as an integer.

Returns: the nearest cardinal direction as an integer.

Note: This is the reverse of cardinal(T).

Definition at line 572 of file Angle.hpp.

Referenced by operator+=().

◆ quadrant()

template<typename T>

unsigned GeographicLib::AngleT< T >::quadrant ( ) const

inline

Definition at line 690 of file Angle.hpp.

◆ operator-() [1/2]

template<typename T>

AngleT< T > GeographicLib::AngleT< T >::operator- ( ) const

inline

Return the negated AngleT.

Returns: minus the AngleT

Definition at line 587 of file Angle.hpp.

References AngleT().

◆ operator+=()

template<typename T>

AngleT< T > & GeographicLib::AngleT< T >::operator+= ( const AngleT< T > & p )

inline

Implement the += operator.

Parameters

[in] p the AngleT to be added.

Returns: the current AngleT after the addition.

Definition at line 592 of file Angle.hpp.

References AngleT(), c(), and ncardinal().

◆ operator-=()

template<typename T>

AngleT< T > & GeographicLib::AngleT< T >::operator-= ( const AngleT< T > & p )

inline

Implement the -= operator.

Parameters

[in] p the AngleT to be subtracted.

Returns: the current AngleT after the subtraction.

Definition at line 611 of file Angle.hpp.

References AngleT().

◆ operator+()

template<typename T>

AngleT< T > GeographicLib::AngleT< T >::operator+ ( const AngleT< T > & p ) const

inline

Implement the + operator.

Parameters

[in] p the AngleT to be added.

Returns: the result of the addition; the current AngleT is not modified.

Definition at line 605 of file Angle.hpp.

References AngleT(), and t().

◆ operator-() [2/2]

template<typename T>

AngleT< T > GeographicLib::AngleT< T >::operator- ( const AngleT< T > & p ) const

inline

Implement the - operator.

Parameters

[in] p the AngleT to be subtracted.

Returns: the result of the subtraction; the current AngleT is not modified.

Definition at line 617 of file Angle.hpp.

References AngleT(), and t().

◆ zerop()

template<typename T>

bool GeographicLib::AngleT< T >::zerop ( T mult = 0 ) const

inline

Test for a zero angle.

Parameters

[in] mult multiplier of machine epsilon used in test (default 0).

Returns: true if this AngleT is withing mult ε of zero.

Definition at line 623 of file Angle.hpp.

◆ operator==()

template<typename T>

bool GeographicLib::AngleT< T >::operator== ( const AngleT< T > & p ) const

inline

Implement the == operator.

Parameters

[in] p the AngleT to be compared against

Returns: *this == p.

Definition at line 630 of file Angle.hpp.

References AngleT(), and t().

◆ round()

template<typename T>

AngleT< T > & GeographicLib::AngleT< T >::round ( )

inline

"Round" the AngleT the == operator.

Returns: the AngleT with tiny values of s() and c() set to ±0.

This ensures that the smallest gaps between sine and cosine values is ε/2048.

Definition at line 636 of file Angle.hpp.

References AngleT().

Referenced by GeographicLib::Triaxial::GeodesicLine3::GeodesicLine3(), GeographicLib::Triaxial::Geodesic3::Inverse(), and GeographicLib::Triaxial::GeodesicLine3::Position().

◆ renormalize()

template<typename T>

AngleT< T > & GeographicLib::AngleT< T >::renormalize ( )

inline

Renormalize the sine and cosine values

Returns: the modified AngleT.

During arithmetic operations on AngleT object, no effort is mode to ensure that (s(), c()) remains on the unit circle. This function corrects this.

Definition at line 655 of file Angle.hpp.

References AngleT().

◆ setn()

template<typename T>

AngleT< T > & GeographicLib::AngleT< T >::setn ( T n = 0 )

inline

Reduce the angle to [−180°, +180°]

Returns: the modified AngleT, obtained by setting n() to zero.

Definition at line 662 of file Angle.hpp.

References AngleT(), and n().

Referenced by GeographicLib::Triaxial::Geodesic3::Inverse(), GeographicLib::Triaxial::GeodesicLine3::pos1(), and GeographicLib::Triaxial::GeodesicLine3::Position().

◆ setn0()

template<typename T>

AngleT< T > & GeographicLib::AngleT< T >::setn0 ( T n = 0 )

inline

Reduce the angle to (−180°, +180°]

Returns: the modified AngleT.

This differs from setn(T) by treating −180° as +180° less 1 turn.

Definition at line 675 of file Angle.hpp.

References AngleT(), and n().

◆ setquadrant()

template<typename T>

AngleT< T > & GeographicLib::AngleT< T >::setquadrant ( unsigned q )

inline

Set the quadrant of an AngleT the angle to (−180°, +180°]

Parameters

[in] q the quadrant.

Returns: the modified AngleT.

This sets the signs of s() and c() according to e q.

Note: Only the low two bits of q are used. n() is unchanged.

Definition at line 682 of file Angle.hpp.

References AngleT().

Referenced by GeographicLib::Triaxial::Geodesic3::Inverse(), and GeographicLib::Triaxial::GeodesicLine3::fline::fics::setquadrant().

◆ reflect()

template<typename T>

AngleT< T > & GeographicLib::AngleT< T >::reflect	(	bool	flips,
		bool	flipc = false,
		bool	swapp = false )

inline

Reflect the angle is various ways

Parameters

[in]	flips	change the sign of s()
[in]	flipc	change the sign of c()
[in]	swapp	swap s() and c()

Returns: the modified AngleT.

Note: The operations are carried out in the order of the parameters.

Definition at line 696 of file Angle.hpp.

References AngleT(), and std::swap().

Referenced by BiaxialCoords(), GeographicLib::Triaxial::Geodesic3::Inverse(), GeographicLib::Triaxial::GeodesicLine3::fline::fics::pos1(), and GeographicLib::Triaxial::GeodesicLine3::Position().

◆ base()

template<typename T>

AngleT< T > GeographicLib::AngleT< T >::base ( ) const

inline

Return an AngleT in [−180°, +180°].

Returns: the new AngleT.

This returns the AngleT with n() set to zero.

Definition at line 642 of file Angle.hpp.

References AngleT().

Referenced by GeographicLib::Triaxial::Geodesic3::Inverse(), main(), and rebase().

◆ rebase()

template<typename T>

AngleT< T > GeographicLib::AngleT< T >::rebase ( const AngleT< T > & c ) const

inline

Return an AngleT centered about another AngleT

Parameters

[in] c the center AngleT

Returns: the new AngleT.

This returns the result of adjusting n() so that the new AngleT is with ±180° of c.

Definition at line 647 of file Angle.hpp.

References AngleT(), base(), c(), n0(), and t().

Referenced by GeographicLib::Triaxial::GeodesicLine3::Position().

◆ flipsign()

template<typename T>

AngleT< T > GeographicLib::AngleT< T >::flipsign ( T mult ) const

inline

Return an AngleT with the sign optionally flipped

Parameters

[in] mult

Returns: the new AngleT.

return signbit(mult) ? -*this : *this.

Definition at line 705 of file Angle.hpp.

References AngleT().

Referenced by GeographicLib::Triaxial::Geodesic3::Inverse(), and GeographicLib::Triaxial::GeodesicLine3::Position().

◆ modang()

template<typename T>

AngleT< T > GeographicLib::AngleT< T >::modang ( T m ) const

inline

The "reduced latitude" operation.

Parameters

[in] m

Returns: the atan(m * tan(*this))

However the quadrant of the result tracking that of *this through multiples turns.

Definition at line 711 of file Angle.hpp.

References AngleT(), and NaN().

Referenced by GeographicLib::Triaxial::Conformal3::beta(), BiaxialCoords(), GeographicLib::Triaxial::Cartesian3::meridianplane(), GeographicLib::Triaxial::Conformal3::omega(), GeographicLib::Triaxial::Conformal3::x(), and GeographicLib::Triaxial::Conformal3::y().

◆ DecodeLatLon()

template<typename T = Math::real>

void GeographicLib::AngleT< T >::DecodeLatLon	(	const std::string &	stra,
		const std::string &	strb,
		AngleT< T > &	lat,
		AngleT< T > &	lon,
		bool	longfirst = false )

static

Interpret two strings as latitude and longitude.

Parameters

[in]	stra	the first string
[in]	strb	the second string
[out]	lat	the latitude
[out]	lon	the longitude
[in]	longfirst	(defaultfirst) whether the longitude is given first.

In the absence of hemisphere indicators (N/S for latitude and E/W for longitude), it is assumed that the first string is the latitude. Setting longfirst = true uses the opposite convention. The hemisphere indicators can also be used to set the signs of the angles.

Definition at line 39 of file Angle.cpp.

References AngleT(), GeographicLib::DMS::Decode(), GeographicLib::DMS::LATITUDE, GeographicLib::DMS::LONGITUDE, and GeographicLib::DMS::NONE.

◆ DecodeAzimuth()

template<typename T = Math::real>

AngleT< T > GeographicLib::AngleT< T >::DecodeAzimuth ( const std::string & azistr )

static

Interpret a string as azimuth

Parameters

[in] azistr the string representing the azimuth

Returns: the azimuth

The hemisphere indicators E/W can be used to set the sign of the azimuth.

Definition at line 62 of file Angle.cpp.

References AngleT(), GeographicLib::DMS::Decode(), and GeographicLib::DMS::LATITUDE.

◆ LatLonString()

template<typename T>

string GeographicLib::AngleT< T >::LatLonString	(	AngleT< T >	lat,
		AngleT< T >	lon,
		int	prec,
		bool	dms = false,
		char	dmssep = '\0',
		bool	longfirst = false )

static

Create a string for a latitude-longitude pair.

Parameters

[in]	lat	the latitude.
[in]	lon	the longitude.
[in]	prec	the precision relative to 1°.
[in]	dms	(default false) whether to use degrees/minutes/seconds as opposed to decimal degrees
[in]	dmssep	(default NULL) the separator to use with the DMS representation instead of d ' ".
[in]	longfirst	(default false) whether to list the longitude first.

Returns: string representation

With dms = true the hemisphere indicators N/S and E/W are used to indicator the signs of the latitude and longitude.

Definition at line 72 of file Angle.cpp.

References AngleT(), GeographicLib::DMS::Encode(), GeographicLib::DMS::LATITUDE, GeographicLib::DMS::LONGITUDE, and GeographicLib::DMS::NUMBER.

◆ AzimuthString()

template<typename T>

string GeographicLib::AngleT< T >::AzimuthString	(	AngleT< T >	azi,
		int	prec,
		bool	dms = false,
		char	dmssep = '\0' )

static

Create a string for an azimuth.

Parameters

[in]	azi	the azimuth.
[in]	prec	the precision relative to 1°.
[in]	dms	(default false) whether to use degrees/minutes/seconds as opposed to decimal degrees
[in]	dmssep	(default NULL) the separator to use with the DMS representation instead of d ' ".

Returns: string representation

With dms = true the hemisphere indicators and E/W is used to indicator the sign of the azimuth.

Definition at line 86 of file Angle.cpp.

References AngleT(), GeographicLib::DMS::AZIMUTH, GeographicLib::DMS::Encode(), and GeographicLib::DMS::NUMBER.

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

Public Member Functions

Static Public Member Functions

Creating AngleT objects.

Detailed Description

Constructor & Destructor Documentation

◆ AngleT() [1/3]

◆ AngleT() [2/3]

◆ AngleT() [3/3]

Member Function Documentation

◆ degrees() [1/2]

◆ radians() [1/2]

◆ lam() [1/2]

◆ NaN()

◆ cardinal()

◆ eps()

◆ s()

◆ c()

◆ t()

◆ n()

◆ n0()

◆ operator T()

◆ degrees() [2/2]

◆ degrees0()

◆ radians() [2/2]

◆ radians0()

◆ lam() [2/2]

◆ nearest()

◆ ncardinal()

◆ quadrant()

◆ operator-() [1/2]

◆ operator+=()

◆ operator-=()

◆ operator+()

◆ operator-() [2/2]

◆ zerop()

◆ operator==()

◆ round()

◆ renormalize()

◆ setn()

◆ setn0()

◆ setquadrant()

◆ reflect()

◆ base()

◆ rebase()

◆ flipsign()

◆ modang()

◆ DecodeLatLon()

◆ DecodeAzimuth()

◆ LatLonString()

◆ AzimuthString()