Loading...
Searching...
No Matches
supernovas::Angle Class Reference
Helpers and utilities

A representation of a regularized angle, which can be expressed in various commonly used angular units as needed. More...

`#include <supernovas.h>`

Inheritance diagram for supernovas::Angle:

## Public Member Functions

| Angle (const std::string &str)
| Instantiates an angle from its string representation, either as decimal degrees or as [-]DDD:MM:SS.SSS.
| Angle (double radians)
| Instantiates a new angle with the specified value in radians.
double | arcmin () const
| Returns the angle in arc minutes.
double | arcsec () const
| Returns the angle in arc seconds.
double | deg () const
| Returns the angle in degrees.
bool | equals (const Angle &angle, double precision=Unit::uas) const
| Checks if this angle instance equals another within the specified absolute precision.
double | fraction () const
| Returns the angle as a fraction of the circle.
double | mas () const
| Returns the angle in milliarcseconds.
bool | operator!= (const Angle &angle) const
| Checks if this angle instance differs from another by more than 1 μas.
virtual Angle | operator+ (const Angle &r) const
| Returns a new angle that is the sum of this angle and the specified other angle.
virtual Angle | operator- (const Angle &r) const
| Returns a new angle that is the difference of this angle and the specified other angle.
bool | operator== (const Angle &angle) const
| Checks if this angle instance equals another within the 1 μas.
double | rad () const
| Returns the angle in radians.
std::string | SI_unit () const override
virtual std::string | to_string (enum novas_separator_type separator, int decimals=3) const
| Provides a DDD:MM:SS.SSS representation of the angle with the specified separators and decimal places for the arc seconds.
std::string | to_string (int decimals=3) const override
| Returns a human readable representation of this scalar quantity.
double | uas () const
| Returns the angle in microarcseconds.
Public Member Functions inherited from supernovas::Scalar
virtual | ~Scalar ()
bool | equals (const Scalar &other, double precision) const
| Checks if this scalar quantity is the same as another, within the specified precision.
double | SI_value () const
| The value of this scalar quantity in S.I.
Public Member Functions inherited from supernovas::Validating
bool | is_valid () const
| Returns the previously set 'valid' state of the implementing instance.
| operator bool () const
| Objects that implement Validating can be used in conditionals directly, without explicitly calling is_valid().

## Static Public Member Functions

static const Angle & | undefined ()
| Returns a reference to a statically defined standard invalid angle.

## Static Public Attributes

static constexpr int | east = 1
| East direction sign, e.g 19.5 * Unit::deg * Angle::east for 19.5 deg East.
static constexpr int | north = 1
| North direction sign, e.g 33.4 * Unit::deg * Angle::north for 33.4 deg North.
static constexpr int | south = -1
| South direction sign, e.g 90.0 * Unit::deg * Angle::south for the South pole.
static constexpr int | west = -1
| West direction sign, e.g 155.1 * Unit::deg * Angle::west for 155.1 deg West.

## Additional Inherited Members

Protected Member Functions inherited from supernovas::Scalar
| Scalar ()
| Instantiates a standard undefined (invalid) scalar quantity with NAN value.
| Scalar (double SI_value)
| Instantiates a scalar quantity with an initializing value in standard S.I.
Protected Member Functions inherited from supernovas::Validating
| Validating ()
| dummy constructor;
Protected Attributes inherited from supernovas::Scalar
double | _value
| The value in S.I. units.
Protected Attributes inherited from supernovas::Validating
bool | _valid = false
| the state variable.

## Detailed Description

A representation of a regularized angle, which can be expressed in various commonly used angular units as needed.

It can also be used to instantiate angles from decimal or [+]DDD:MM:SS.SSS string representations of the angle in degrees.

Since
  1.6

See also
  TimeAngle

## Constructor & Destructor Documentation

## Angle() [1/2]

supernovas::Angle::Angle | ( | double | radians | ) |

explicit

Instantiates a new angle with the specified value in radians.

You can use the Unit class to convert angles expressed in other units to radians. For example, to set 15.0 degrees, you might write:

Angle a(15.0 * Unit::deg);
supernovas::Unit::deg
static constexpr double deg
[rad] 1 degree in radians
Definition supernovas.h:173

Parameters

  radians | [rad] the initializing value.

Since
  1.6

See also
  TimeAngle, Unit

References supernovas::Scalar::Scalar(), and supernovas::Validating::is_valid().

## Angle() [2/2]

supernovas::Angle::Angle | ( | const std::string & | str | ) |

explicit

Instantiates an angle from its string representation, either as decimal degrees or as [-]DDD:MM:SS.SSS.

Other than colons, the degrees, minutes, and seconds components may be separated by the symbols d, m, or white spaces of cobination of the above. To learn more about what exact representations are supported see novas:novas_str_degrees().

Parameters

  str | a string specifying an angle either as decimal degrees or as DDD:MM:SS.SSS and variants thereof.

Since
  1.6

See also
  novas:novas_str_degrees()

References deg(), and novas_str_degrees().

## Member Function Documentation

## arcmin()

double supernovas::Angle::arcmin | ( |  | ) | const

Returns the angle in arc minutes.

Returns
  [arcmin] the angle in arc minutes, usually in the [-10800:10800) range, although subclasses may support different ranges for the returned value.

Since
  1.6

See also
  rad(), deg(), arcsec(), mas(), uas()

References supernovas::Scalar::_value, and supernovas::Unit::arcmin.

## arcsec()

double supernovas::Angle::arcsec | ( |  | ) | const

Returns the angle in arc seconds.

Returns
  [arcsec] the angle in arc seconds, usually in the [-648000:648000) range, although subclasses may support different ranges for the returned value.

Since
  1.6

See also
  rad(), deg(), arcmin(), mas(), uas()

References supernovas::Scalar::_value, and supernovas::Unit::arcsec.

Referenced by supernovas::GeodeticObserver::gcrs_position_at(), and supernovas::GeodeticObserver::gcrs_velocity_at().

## deg()

double supernovas::Angle::deg | ( |  | ) | const

Returns the angle in degrees.

Returns
  [degrees] the angle in degrees, usually in the [-180:180) range, although subclasses may support different ranges for the returned value.

Since
  1.6

See also
  rad(), arcmin(), arcsec(), mas(), uas()

References supernovas::Scalar::_value, and supernovas::Unit::deg.

Referenced by Angle(), supernovas::CatalogEntry::CatalogEntry(), supernovas::Spherical::distance_to(), supernovas::Time::lst(), supernovas::Time::next_moon_phase(), supernovas::Source::rises_above(), supernovas::Source::sets_below(), supernovas::Equatorial::to_ecliptic(), supernovas::Equatorial::to_galactic(), and to_string().

## equals()

bool supernovas::Angle::equals | ( | const Angle & | angle,
|  | double | precision = Unit::uas ) const

Checks if this angle instance equals another within the specified absolute precision.

Parameters

  angle | another angle
  precision | [rad] the abolute precision to use when testing for equality. If the two angles are closer on the 2π circle to each other than this precision, then they are consideredc equal, otherwise not.

Returns
  true if the two angles match within the specified precision, or else false.

Since
  1.6

See also
  operator==(), operator!=()

References supernovas::Scalar::_value, and supernovas::Constant::two_pi.

Referenced by operator!=(), and operator==().

## fraction()

double supernovas::Angle::fraction | ( |  | ) | const

Returns the angle as a fraction of the circle.

Returns
  the angle as a fraction of the circle, usually in the [0:1) range.

Since
  1.6

References supernovas::Scalar::_value, and supernovas::Constant::two_pi.

## mas()

double supernovas::Angle::mas | ( |  | ) | const

Returns the angle in milliarcseconds.

Returns
  [mas] the angle in milliarcseconds, usually in the [-6.48e8:6.48e8) range, although subclasses may support different ranges for the returned value.

Since
  1.6

See also
  rad(), deg(), arcmin(), arcsec(), uas()

References supernovas::Scalar::_value, and supernovas::Unit::mas.

## operator!=()

bool supernovas::Angle::operator!= | ( | const Angle & | angle | ) | const

Checks if this angle instance differs from another by more than 1 μas.

Parameters

  angle | another angle

Returns
  true if the two angles differ by more than 1 μas, or else false.

Since
  1.6

See also
  equals(), operator==()

References equals().

## operator+()

Angle supernovas::Angle::operator+ | ( | const Angle & | r | ) | const

virtual

Returns a new angle that is the sum of this angle and the specified other angle.

Parameters

  r | the other angle on the right-hand-side.

Returns
  the sum of this angle and the argument, as a new angle.

Since
  1.6

See also
  operator-()

Reimplemented in supernovas::TimeAngle.

References supernovas::Validating::is_valid(), and rad().

Referenced by supernovas::TimeAngle::operator+().

## operator-()

Angle supernovas::Angle::operator- | ( | const Angle & | r | ) | const

virtual

Returns a new angle that is the difference of this angle and the specified other angle.

Parameters

  r | the other angle on the right-hand-side.

Returns
  the difference of this angle and the argument, as a new angle.

Since
  1.6

See also
  operator+()

Reimplemented in supernovas::TimeAngle.

References supernovas::Validating::is_valid(), and rad().

Referenced by supernovas::TimeAngle::operator-().

## operator==()

bool supernovas::Angle::operator== | ( | const Angle & | angle | ) | const

Checks if this angle instance equals another within the 1 μas.

Parameters

  angle | another angle

Returns
  true if the two angles match within 1 μas, or else false.

Since
  1.6

See also
  equals(), operator!=()

References equals().

## rad()

double supernovas::Angle::rad | ( |  | ) | const

Returns the angle in radians.

Returns
  [rad] the angle in radians, usually in the [-π:π) range, although subclasses may support different ranges for the returned value.

Since
  1.6

See also
  deg(), arcmin(), arcsec(), mas(), uas()

References supernovas::Scalar::_value.

Referenced by supernovas::GeodeticObserver::GeodeticObserver(), supernovas::Orbital::eccentricity(), supernovas::Ecliptic::equals(), supernovas::Equatorial::equals(), supernovas::Galactic::equals(), supernovas::Horizontal::equals(), supernovas::Spherical::equals(), supernovas::Apparent::from_cirs(), supernovas::Orbital::from_mean_motion(), supernovas::Apparent::from_tod(), supernovas::Orbital::inclination(), supernovas::Ecliptic::offset(), supernovas::Equatorial::offset(), supernovas::Galactic::offset(), supernovas::Horizontal::offset(), operator+(), supernovas::TimeAngle::operator+(), operator-(), supernovas::TimeAngle::operator-(), supernovas::OrbitalSystem::orbit(), supernovas::CatalogEntry::parallax(), supernovas::Orbital::pole(), and supernovas::OrbitalSystem::pole().

## SI_unit()

std::string supernovas::Angle::SI_unit | ( |  | ) | const

override virtual

Implements supernovas::Scalar.

## to_string() [1/2]

std::string supernovas::Angle::to_string | ( | enum novas_separator_type | separator,
|  | int | decimals = 3 ) const

virtual

Provides a DDD:MM:SS.SSS representation of the angle with the specified separators and decimal places for the arc seconds.

Parameters

  separator | the type of separators / unit markers used to distinguish the degree, minute, and second components.
  decimals | (optional) [0:9] the number of decimal places to print for the arc seconds component (default: 3).

Returns
  the strung representation of this angle in degrees.

See also
  TimeAngle::to_string()

Reimplemented in supernovas::TimeAngle.

References deg(), and novas_print_dms().

## to_string() [2/2]

std::string supernovas::Angle::to_string | ( | int | decimals = 3 | ) | const

inline override virtual

Returns a human readable representation of this scalar quantity.

Subclasses may override the default implementation to provide their own.

Parameters

  decimals | (optional) [0:16] Number of decimal places to print (default: 3).

Returns
  a string representation of this scalar quantity.

Since
  1.6

Reimplemented from supernovas::Scalar.

References NOVAS_SEP_UNITS_AND_SPACES, and to_string().

Referenced by to_string(), supernovas::CatalogSource::to_string(), supernovas::Equatorial::to_string(), supernovas::Site::to_string(), and supernovas::Spherical::to_string().

## uas()

double supernovas::Angle::uas | ( |  | ) | const

Returns the angle in microarcseconds.

Returns
  [μas] the angle in microarcseconds, usually in the [-6.48e11:6.48e11) range, although subclasses may support different ranges for the returned value.

Since
  1.6

See also
  rad(), deg(), arcmin(), arcsec(), mas()

References supernovas::Scalar::_value, and supernovas::Unit::uas.

Referenced by supernovas::GeodeticObserver::equals().

## undefined()

const Angle & supernovas::Angle::undefined | ( |  | ) |

static

Returns a reference to a statically defined standard invalid angle.

Sunch invalid angles may be used inside any object that is invalid itself.

Returns
  a reference to a static standard invalid angle.

Referenced by supernovas::Track< CoordType >::latitude_at(), and supernovas::Track< CoordType >::longitude_at().

## Member Data Documentation

## east

int supernovas::Angle::east = 1

static constexpr

East direction sign, e.g 19.5 * Unit::deg * Angle::east for 19.5 deg East.

## north

int supernovas::Angle::north = 1

static constexpr

North direction sign, e.g 33.4 * Unit::deg * Angle::north for 33.4 deg North.

## south

int supernovas::Angle::south = -1

static constexpr

South direction sign, e.g 90.0 * Unit::deg * Angle::south for the South pole.

## west

int supernovas::Angle::west = -1

static constexpr

West direction sign, e.g 155.1 * Unit::deg * Angle::west for 155.1 deg West.