Loading...
Searching...
No Matches
supernovas::CalendarDate Class Reference
Time of observation and astronomical timescales

A time specified in a specific type of calendar (Gregorian, Roman, or astronomical). More...

`#include <supernovas.h>`

Inheritance diagram for supernovas::CalendarDate:

## Public Member Functions

| CalendarDate (const Calendar &calendar, double jd)
| Instantiates a date / time in the specified calendar, using the specified Julian Date.
| CalendarDate (const Calendar &calendar, int year, int month, int day, const TimeAngle &time=TimeAngle::zero())
| Instantiates a date / time in the specified calendar, using the specified date components.
int | break_down (struct tm *tm) const
| Returns the standard POSIX broken-down time representation for this date.
const Calendar & | calendar () const
const std::string & | day_name () const
| Returns the full (English) name of the day of the week for this date.
int | day_of_month () const
| Returns the day of month component [1:32] of this date.
int | day_of_week () const
| Returns the day of week number [1:7] of this date, starting from 1 (Monday) to 7 (Sunday).
int | day_of_year () const
| Returns the day of year number [1:366] of this date.
bool | equals (const CalendarDate &date, const Interval &precision) const
| Checks if this calendar date is the same as the specified other date, within the specified tolerance.
bool | equals (const CalendarDate &date, double seconds=Unit::ms) const
| Checks if this calendar date is the same as the specified other date, within the specified tolerance.
double | jd () const
| Returns the Julian Day corresponding to this calendar date.
double | mjd () const
| Returns the Modified Julian Day corresponding to this calendar date.
int | month () const
| Returns the calendar month component [1:12] of this date.
const std::string & | month_name () const
| Returns the full (English) name of the month for this date.
bool | operator!= (const CalendarDate &date) const
| Checks if this calendar date differs from the specified other date, by more than 1 ms.
CalendarDate | operator+ (const Interval &interval) const
| Returns a new calendar date that is offset from this calendar date by the specified time interval.
Interval | operator- (const CalendarDate &date) const
| Returns the difference in time between this calendar date and the specified other calendar date.
CalendarDate | operator- (const Interval &interval) const
| Returns a new calendar date that is offset, back in time, from this calendar date by the specified time interval.
bool | operator< (const CalendarDate &date) const
| Checks if this calendar date is before the specified other date.
bool | operator<= (const CalendarDate &date) const
| Checks if this calendar date is the same or before the specified other date at 1 ms resolution.
bool | operator== (const CalendarDate &date) const
| Checks if this calendar date is the same as the specified other date, within 1 ms.
bool | operator> (const CalendarDate &date) const
| Checks if this calendar date is after the specified other date.
bool | operator>= (const CalendarDate &date) const
| Checks if this calendar date is the same or after the specified other date at 1 ms resolution.
CalendarDate | operator>> (const Calendar &calendar) const
| Returns this date in the specified other calendar.
const std::string & | short_day_name () const
| Returns the short 3-letter (English) abbreviation of the day of the week for this date.
const std::string & | short_month_name () const
| Returns the short 3-letter (English) abbreviation of the month name for this date.
const TimeAngle & | time_of_day () const
| Returns the time-of-date component of this calendar date.
CalendarDate | to_calendar (const Calendar &calendar) const
| Returns this date in the specified other calendar.
std::string | to_date_string (enum novas_date_format fmt=NOVAS_YMD) const
| Returns the numerical date only representation, in the specified component order, e.g.
std::string | to_long_date_string () const
| Returns the date component in long-form string representation.
std::string | to_string (enum novas_date_format fmt=NOVAS_YMD, int decimals=0) const
| Returns a string representation of this calendar date, given the requested date format and decimal places to print for the seconds component.
std::string | to_string (int decimals) const
| Returns a string representation of this calendar date, using the YMD format and the specified decimal places to print for the seconds component.
Time | to_time (const EOP &eop=EOP::undefined(), novas_timescale timescale=NOVAS_UTC) const
| Converts this calendar date to ans astronomical time representation, given the specified Earth Orientation Parameters, and astronomical timescale.
Time | to_time (int leap_seconds, double dut1, novas_timescale timescale=NOVAS_UTC) const
| Converts this calendar date to and astronomical time representation, given the specified Earth Orientation Parameters, and astronomical timescale.
time_t | unix_time () const
| Returns the UNIX time for this calendar date.
int | year () const
| Returns the calendar year component of this date.
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 CalendarDate & | undefined ()
| Returns a reference to a statically defined standard undefined / invalid calendar date instance.

## Additional Inherited Members

Protected Member Functions inherited from supernovas::Validating
| Validating ()
| dummy constructor;
Protected Attributes inherited from supernovas::Validating
bool | _valid = false
| the state variable.

## Detailed Description

A time specified in a specific type of calendar (Gregorian, Roman, or astronomical).

Calendar dates allow for broken-down (year, month, day-of-month, day-of-week, day-of-year, and time-of-day) representation. Unlike the related Time class, calendar dates are not timescale aware. They may be used typically to refer to UTC dates, or else whatevertimescale the user had in mind when constructing it. It has a lesser precision than Time, at the 100 μs level, limited by the double-precision representation of Julian dates. However, that level of precision is still sufficient for most applications.

Since
  1.6

See also
  Time

## Constructor & Destructor Documentation

## CalendarDate() [1/2]

supernovas::CalendarDate::CalendarDate | ( | const Calendar & | calendar,
|  | int | year,
|  | int | month,
|  | int | day,
|  | const TimeAngle & | time = TimeAngle::zero() )

Instantiates a date / time in the specified calendar, using the specified date components.

Parameters

  calendar | calendar, in which the date is specified.
  year | [yr] calendar year
  month | [month] calendar month [1:12]
  day | [day] calendar day-of-month [1:31]
  time | time of day component.

Since
  1.6

See also
  Calendar::date()

References supernovas::Validating::_valid, calendar(), supernovas::TimeAngle::hours(), month(), novas_jd_from_date(), and year().

## CalendarDate() [2/2]

supernovas::CalendarDate::CalendarDate | ( | const Calendar & | calendar,
|  | double | jd )

Instantiates a date / time in the specified calendar, using the specified Julian Date.

Parameters

  calendar | calendar, in which the date is specified.
  jd | [day] Julian date (in the timescale of preference).

Since
  1.6

See also
  equals(), operator!=()

References supernovas::Validating::_valid, calendar(), supernovas::Unit::hour, jd(), and novas_jd_to_date().

## Member Function Documentation

## break_down()

int supernovas::CalendarDate::break_down | ( | struct tm * | tm | ) | const

Returns the standard POSIX broken-down time representation for this date.

Parameters

  [out] | tm | Pointer to the broken-down time structure in which to return the result.

Returns
  0 if successful, or else -1 if the argument is NULL (errno will be set to EINVAL).

Since
  1.6

See also
  year(), month(), day_of_year(), day_of_month(), day_of_week(), time_of_day()

References supernovas::Validating::_valid, day_of_week(), and day_of_year().

## calendar()

const Calendar & supernovas::CalendarDate::calendar | ( |  | ) | const

inline

Referenced by CalendarDate(), CalendarDate(), operator+(), operator-(), operator>>(), and to_calendar().

## day_name()

const std::string & supernovas::CalendarDate::day_name | ( |  | ) | const

Returns the full (English) name of the day of the week for this date.

Returns
  the full name of the day of the week, e.g. "Wednesday".

Since
  1.6

See also
  short_day_name(), day_of_week()

References day_of_week().

## day_of_month()

int supernovas::CalendarDate::day_of_month | ( |  | ) | const

Returns the day of month component [1:32] of this date.

Returns
  [day] day of month component, starting from 1

Since
  1.6

See also
  month(), day_of_year(), day_of_week()

## day_of_week()

int supernovas::CalendarDate::day_of_week | ( |  | ) | const

Returns the day of week number [1:7] of this date, starting from 1 (Monday) to 7 (Sunday).

Returns
  [day] the day of the week stating from 1 (Monday) to 7 (Sunday)

Since
  1.6

See also
  day_name(), short_day_name(), day_of_month(), day_of_year()

References novas_day_of_week().

Referenced by break_down(), day_name(), and short_day_name().

## day_of_year()

int supernovas::CalendarDate::day_of_year | ( |  | ) | const

Returns the day of year number [1:366] of this date.

Returns
  the day of year number, starting from 1.

Since
  1.6

See also
  year(), day_of_month(), day_of_week()

References novas_day_of_year().

Referenced by break_down().

## equals() [1/2]

bool supernovas::CalendarDate::equals | ( | const CalendarDate & | date,
|  | const Interval & | precision ) const

Checks if this calendar date is the same as the specified other date, within the specified tolerance.

Parameters

  date | the other date to compare to this one.
  precision | tolerance for equality check (default: 1 ms).

Returns
  true if this date is the same as the other calendar date, within the specified tolerance, or else false.

Since
  1.6

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

References equals(), and supernovas::Interval::seconds().

## equals() [2/2]

bool supernovas::CalendarDate::equals | ( | const CalendarDate & | date,
|  | double | seconds = Unit::ms ) const

Checks if this calendar date is the same as the specified other date, within the specified tolerance.

Parameters

  date | the other date to compare to this one.
  seconds | [s] tolerance for equality check.

Returns
  true if this date is the same as the other calendar date, within the specified tolerance, or else false.

Since
  1.6

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

References supernovas::Unit::day, and jd().

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

## jd()

double supernovas::CalendarDate::jd | ( |  | ) | const

Returns the Julian Day corresponding to this calendar date.

Returns
  [day] the Julian Date corresponding to this calendar date. Note, that Julian dates start at noon, not midnight.

Since
  1.6

See also
  mjd()

Referenced by CalendarDate(), equals(), operator+(), operator-(), operator-(), operator<(), operator<=(), operator>=(), and to_time().

## mjd()

double supernovas::CalendarDate::mjd | ( |  | ) | const

Returns the Modified Julian Day corresponding to this calendar date.

Returns
  [day] the Modified Julian Day (MJD) corresponding to this calendar date. Modified Julian days start at midnight.

Since
  1.6

See also
  mjd()

References NOVAS_JD_MJD0.

## month()

int supernovas::CalendarDate::month | ( |  | ) | const

Returns the calendar month component [1:12] of this date.

Returns
  [month] calendar month [1:12]

Since
  1.6

See also
  month_name(), short_month_name(), year(), day_of_month()

Referenced by CalendarDate().

## month_name()

const std::string & supernovas::CalendarDate::month_name | ( |  | ) | const

Returns the full (English) name of the month for this date.

Returns
  the full name of the month, e.g. "January".

Since
  1.6

See also
  short_month_name(), month()

## operator!=()

bool supernovas::CalendarDate::operator!= | ( | const CalendarDate & | date | ) | const

Checks if this calendar date differs from the specified other date, by more than 1 ms.

Parameters

  date | the other date to compare to this one.

Returns
  true if this date differs from the other calendar date, by more than 1 ms, or else false.

Since
  1.6

See also
  equals(), operator!=()

References equals().

## operator+()

CalendarDate supernovas::CalendarDate::operator+ | ( | const Interval & | r | ) | const

Returns a new calendar date that is offset from this calendar date by the specified time interval.

Parameters

  r | the offset interval, on the righ-hand-side of the + operator.

Returns
  a new calendar date, at the specified time offset from this one.

Since
  1.6

See also
  operator-()

References calendar(), supernovas::Interval::days(), supernovas::Validating::is_valid(), and jd().

## operator-() [1/2]

Interval supernovas::CalendarDate::operator- | ( | const CalendarDate & | r | ) | const

Returns the difference in time between this calendar date and the specified other calendar date.

Parameters

  r | the other calendar date, on the right-hand-side of the - operator.

Returns
  the time difference (interval) between this calendar date and the argument.

Since
  1.6

References supernovas::Unit::day, supernovas::Validating::is_valid(), and jd().

## operator-() [2/2]

CalendarDate supernovas::CalendarDate::operator- | ( | const Interval & | r | ) | const

Returns a new calendar date that is offset, back in time, from this calendar date by the specified time interval.

Parameters

  r | the offset interval, on the righ-hand-side of the - operator.

Returns
  a new calendar date, at the specified time offset, backwards in time, from this one.

Since
  1.6

See also
  operator+()

References calendar(), supernovas::Interval::days(), supernovas::Validating::is_valid(), and jd().

## operator<()

bool supernovas::CalendarDate::operator< | ( | const CalendarDate & | date | ) | const

Checks if this calendar date is before the specified other date.

Parameters

  date | the other date to compare to this one.

Returns
  true if this date precedes the other calendar date, or else false.

Since
  1.6

See also
  operator<=(), operator>()

References jd().

## operator<=()

bool supernovas::CalendarDate::operator<= | ( | const CalendarDate & | date | ) | const

Checks if this calendar date is the same or before the specified other date at 1 ms resolution.

Parameters

  date | the other date to compare to this one.

Returns
  true if this date is the same or before the other calendar date, or else false.

Since
  1.6

See also
  operator<(), operator>=()

References supernovas::Unit::day, jd(), and supernovas::Unit::ms.

## operator==()

bool supernovas::CalendarDate::operator== | ( | const CalendarDate & | date | ) | const

Checks if this calendar date is the same as the specified other date, within 1 ms.

Parameters

  date | the other date to compare to this one.

Returns
  true if this date is the same as the other calendar date, within 1 ms, or else false.

Since
  1.6

See also
  equals(), operator!=()

References equals().

## operator>()

bool supernovas::CalendarDate::operator> | ( | const CalendarDate & | date | ) | const

Checks if this calendar date is after the specified other date.

Parameters

  date | the other date to compare to this one.

Returns
  true if this date is after the other calendar date, or else false.

Since
  1.6

See also
  operator>=(), operator<()

## operator>=()

bool supernovas::CalendarDate::operator>= | ( | const CalendarDate & | date | ) | const

Checks if this calendar date is the same or after the specified other date at 1 ms resolution.

Parameters

  date | the other date to compare to this one.

Returns
  true if this date is the same or after the other calendar date, or else false.

Since
  1.6

See also
  operator>(), operator<=(),

References supernovas::Unit::day, jd(), and supernovas::Unit::ms.

## operator>>()

CalendarDate supernovas::CalendarDate::operator>> | ( | const Calendar & | calendar | ) | const

Returns this date in the specified other calendar.

Same as to_calendar().

Parameters

  calendar | a calendar in which to express this date

Returns
  this date, expressed in the specified other calendar.

Since
  1.6

See also
  to_calendar(Calendar&)

References calendar(), supernovas::Validating::is_valid(), and to_calendar().

## short_day_name()

const std::string & supernovas::CalendarDate::short_day_name | ( |  | ) | const

Returns the short 3-letter (English) abbreviation of the day of the week for this date.

Returns
  the full name of the day of the week, e.g. "Wed".

Since
  1.6

See also
  day_name(), day_of_week()

References day_of_week().

Referenced by to_long_date_string().

## short_month_name()

const std::string & supernovas::CalendarDate::short_month_name | ( |  | ) | const

Returns the short 3-letter (English) abbreviation of the month name for this date.

Returns
  the full name of the month, e.g. "Jan".

Since
  1.6

See also
  month_name(), month()

Referenced by to_long_date_string().

## time_of_day()

const TimeAngle & supernovas::CalendarDate::time_of_day | ( |  | ) | const

Returns the time-of-date component of this calendar date.

Returns
  reference to the the time of day component

Since
  1.6

## to_calendar()

CalendarDate supernovas::CalendarDate::to_calendar | ( | const Calendar & | calendar | ) | const

Returns this date in the specified other calendar.

Parameters

  calendar | a calendar in which to express this date

Returns
  this date, expressed in the specified other calendar.

Since
  1.6

See also
  operator>>(Calendar&)

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

Referenced by operator>>().

## to_date_string()

std::string supernovas::CalendarDate::to_date_string | ( | enum novas_date_format | fmt = NOVAS_YMD | ) | const

Returns the numerical date only representation, in the specified component order, e.g.

as "2025-01-31" (for NOVAS_YMD), "31.01.2025" (for NOVAS_DMY), or as "1/31/2025" for NOVAS_MDY).

Parameters

  fmt | The format / order of year (Y), month (M), and day (D) components.

Returns
  the string representation of the date (only) in the specified format.

Since
  1.6

See also
  to_long_date_string(), to_string()

References NOVAS_DMY, NOVAS_MDY, and NOVAS_YMD.

Referenced by to_string().

## to_long_date_string()

std::string supernovas::CalendarDate::to_long_date_string | ( |  | ) | const

Returns the date component in long-form string representation.

E.g. "11 November 2026", or "12 September 490 BCE".

Returns
  the string representation of the date (only) in long form.

Since
  1.6

See also
  to_date_string(), to_string()

References short_day_name(), and short_month_name().

## to_string() [1/2]

std::string supernovas::CalendarDate::to_string | ( | enum novas_date_format | fmt = NOVAS_YMD,
|  | int | decimals = 0 ) const

Returns a string representation of this calendar date, given the requested date format and decimal places to print for the seconds component.

Parameters

  fmt | (optional) The order of the date components (default: NOVAS_YMD)
  decimals | (optional) Number of decimal places to print for the seconds (default: 3)

Returns
  The string representation of the date.

Since
  1.6

See also
  to_string(int), to_date_string(), to_long_date_string()

References NOVAS_SEP_COLONS, and to_date_string().

Referenced by to_string().

## to_string() [2/2]

std::string supernovas::CalendarDate::to_string | ( | int | decimals | ) | const

Returns a string representation of this calendar date, using the YMD format and the specified decimal places to print for the seconds component.

Parameters

  decimals | Number of decimal places to print for the seconds.

Returns
  The string representation of the date.

Since
  1.6

See also
  to_date_string(), to_long_date_string()

References NOVAS_YMD, and to_string().

## to_time() [1/2]

Time supernovas::CalendarDate::to_time | ( | const EOP & | eop = EOP::undefined(),
|  | novas_timescale | timescale = NOVAS_UTC ) const

Converts this calendar date to ans astronomical time representation, given the specified Earth Orientation Parameters, and astronomical timescale.

Not, that calendar dates have accuracy at the 0.1 ms level only, hence the resulting astronomical time will be limited to the same level of precision also.

NOTES:

- If SuperNOVAS was built without cURL support (WITHOUT_CURL or WITHOUT_LIBC build configuration options), then automatic fetching of the leap seconds and the UT1 - UTC differennce is not possible. You must set a valid EOP explicitly.

Parameters

  eop | (optional) Earth Orientation Parameters (EOP) for this date, or EOP::undefined() to fetch from IERS for dates after 1 Jan 1956, if possible and allowed.
  timescale | (optional) the astronomical timescale in which this calendar date is defined (default: UTC).

Returns
  an astronomical time instance for this date and input parameters.

Since
  1.6

See also
  novas_set_auto_fetch_eop()

References supernovas::EOP::dUT1(), supernovas::EOP::leap_seconds(), supernovas::Interval::seconds(), and to_time().

## to_time() [2/2]

Time supernovas::CalendarDate::to_time | ( | int | leap_seconds,
|  | double | dut1,
|  | novas_timescale | timescale = NOVAS_UTC ) const

Converts this calendar date to and astronomical time representation, given the specified Earth Orientation Parameters, and astronomical timescale.

Not, that calendar dates have accuracy at the 0.1 ms level only, hence the resulting astronomical time will be limited to the same level of precision also.

Parameters

  leap_seconds | [s] the leap seconds of date, that is the TAI - UTC time difference.
  dut1 | [s] the UT1 - UTC time difference for the date
  timescale | the astronomical timescale in which this calendar date is defined.

Returns
  an astronomical time instance for this date and input parameters.

Since
  1.6

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

Referenced by to_time().

## undefined()

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

static

Returns a reference to a statically defined standard undefined / invalid calendar date instance.

Since
  1.6

Returns
  a reference to the standard undefined calendar date instance.

Referenced by supernovas::Calendar::parse_date().

## unix_time()

time_t supernovas::CalendarDate::unix_time | ( |  | ) | const

Returns the UNIX time for this calendar date.

Returns
  [s] UNIX time, that is seconds since 1 Jan 1970.

Since
  1.6

References supernovas::Unit::day, and NOVAS_JD_J2000.

Referenced by supernovas::EOP::fetch_for().

## year()

int supernovas::CalendarDate::year | ( |  | ) | const

Returns the calendar year component of this date.

Returns
  [yr] the calendar year component. For X BCE, it returns 1 - X. I.e., 45 BCE is returned as -44.

Since
  1.6

See also
  month(), day_of_year()

Referenced by CalendarDate().