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-dat 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, 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 ans 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' stae 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.

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 of observation and astronomical timescales	time of day component.

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).

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).

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".

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

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)

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.

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.

See also: equals(), 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.

See also: equals(), 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.

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.

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]

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".

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.

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.

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.

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.

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.

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.

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.

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.

◆ 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.

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.

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".

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".

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-dat component of this calendar date.

Returns: reference to the the time of day component

◆ 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.

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.

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.

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.

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.

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,
		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.

Parameters

eop	Earth Orientation Parameters (EOP) for this date.
timescale	the astronomical timescale in which this calendar date is defined.

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

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 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.

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.

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.

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.

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

◆ 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.

See also: month(), day_of_year()

Referenced by CalendarDate().

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ CalendarDate() [1/2]

◆ CalendarDate() [2/2]

Member Function Documentation

◆ break_down()

◆ calendar()

◆ day_name()

◆ day_of_month()

◆ day_of_week()

◆ day_of_year()

◆ equals() [1/2]

◆ equals() [2/2]

◆ jd()

◆ mjd()

◆ month()

◆ month_name()

◆ operator!=()

◆ operator+()

◆ operator-() [1/2]

◆ operator-() [2/2]

◆ operator<()

◆ operator<=()

◆ operator==()

◆ operator>()

◆ operator>=()

◆ operator>>()

◆ short_day_name()

◆ short_month_name()

◆ time_of_day()

◆ to_calendar()

◆ to_date_string()

◆ to_long_date_string()

◆ to_string() [1/2]

◆ to_string() [2/2]

◆ to_time() [1/2]

◆ to_time() [2/2]

◆ undefined()

◆ unix_time()

◆ year()