calendar.c File Reference

Various functions to convert between calendar dates and Julian days. More...

Functions
int	cal_date (double tjd, short *restrict year, short *restrict month, short *restrict day, double *restrict hour)
	This function will compute a broken down date on the astronomical calendar given the Julian day input.
double	julian_date (short year, short month, short day, double hour)
	Returns the Julian day for a given astronomical calendar date.
int	novas_day_of_week (double tjd)
	Returns the one-based ISO 8601 day-of-week index of a given Julian Date.
int	novas_day_of_year (double tjd, enum novas_calendar_type calendar, int *restrict year)
	Returns the one-based day index in the calendar year for a given Julian Date.
double	novas_jd_from_date (enum novas_calendar_type calendar, int year, int month, int day, double hour)
	Returns the Julian day for a given calendar date.
int	novas_jd_to_date (double tjd, enum novas_calendar_type calendar, int *restrict year, int *restrict month, int *restrict day, double *restrict hour)
	This function will compute a broken down date on the specified calendar for given the Julian day input.

Detailed Description

Various functions to convert between calendar dates and Julian days.

Date

Created on Mar 6, 2025

Author

Attila Kovacs and G. Kaplan

See also

timescale.c

Function Documentation

cal_date()

int cal_date	(	double	tjd,
		short *restrict	year,
		short *restrict	month,
		short *restrict	day,
		double *restrict	hour )

This function will compute a broken down date on the astronomical calendar given the Julian day input.

Input Julian day can be based on any UT-like time scale (UTC, UT1, TT, etc.) - output time value will have same basis.

NOTES:

1. The Gregorian calendar was introduced on 15 October 1582 only (corresponding to 5 October of the previously used Julian calendar). Prior to it this function returns Julian / Roman calendar dates, e.g. the day before the reform is 1582 October 4. You can use novas_jd_to_date() instead to convert JD days to dates in specific calendars.

2. B.C. dates are indicated with years <=0 according to the astronomical and ISO 8601 convention, i.e., X B.C. as (1-X), so 45 B.C. as -44.

REFERENCES:

1. Fliegel, H. & Van Flandern, T. Comm. of the ACM, Vol. 11, No. 10, October 1968, p. 657.

Parameters

	tjd	[day] Julian date
[out]	year	[yr] Astronomical calendar year. It may be NULL if not required. B.C. years are represented as <=0, i.e. 1 B.C. as 0 and X B.C. as (1 - X)
[out]	month	[month] Astronomical calendar month [1:12]. It may be NULL if not required.
[out]	day	[day] Day of the month [1:31]. It may be NULL if not required.
[out]	hour	[h] Hour of day [0:24]. It may be NULL if not required.

Returns

0

See also

novas_jd_to_date()

novas_get_time()

References NOVAS_ASTRONOMICAL_CALENDAR, and novas_jd_to_date().

julian_date()

double julian_date	(	short	year,
		short	month,
		short	day,
		double	hour )

Returns the Julian day for a given astronomical calendar date.

Input time value can be based on any UT-like time scale (UTC, UT1, TT, etc.) - output Julian day will have the same basis.

NOTES:

1. The Gregorian calendar was introduced on 1582 October 15 only. Prior to that, astronomical dates are Julian/Roman dates, so the day before the reform was 1582 October 4. You can also use novas_jd_from_date() to convert dates with more flexibility.

2. B.C. dates are indicated with years <=0 according to the astronomical and ISO 8601 convention, i.e., X B.C. as (1-X), so 45 B.C. as -44.

3. Added argument range checking in v1.3.0, returning NAN if the month or day are out of the normal range (for a leap year).

REFERENCES:

1. Fliegel, H. & Van Flandern, T. Comm. of the ACM, Vol. 11, No. 10, October 1968, p. 657.

Parameters

year	[yr] Astronomical calendar year. B.C. years can be simply represented as <=0, e.g. 1 B.C. as 0, and X B.C. as (1 - X).
month	[month] Astronomical calendar month [1:12]
day	[day] Astronomical day of month [1:31]
hour	[hr] Hour of day [0:24]

Returns

[day] the fractional Julian date for the input calendar date, ot NAN if the month or day components are out of range.

See also

novas_jd_from_date()

get_utc_to_tt(), get_ut1_to_tt(), tt2tdb()

References NOVAS_ASTRONOMICAL_CALENDAR, and novas_jd_from_date().

novas_day_of_week()

int novas_day_of_week

(

double

tjd

)

Returns the one-based ISO 8601 day-of-week index of a given Julian Date.

The ISO 8601 week begins on Monday, thus index 1 corresponds to Monday, while index 7 is a Sunday.

Parameters

tjd	[day] Julian Date in the timescale of choice. (e.g. UTC-based if you want a UTC-based return value).

Returns

[1:7] The day-of-week index in the same timescale as the input date. 1:Monday ... 7:Sunday.

Since

1.4

Author

Attila Kovacs

See also

novas_day_of_year(), novas_jd_to_date()

References NOVAS_JD_J2000.

novas_day_of_year()

int novas_day_of_year	(	double	tjd,
		enum novas_calendar_type	calendar,
		int *restrict	year )

Returns the one-based day index in the calendar year for a given Julian Date.

Parameters

	tjd	[day] Julian Date in the timescale of choice. (e.g. UTC-based if you want a UTC-based return value).
	calendar	The type of calendar to use: NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_GREGORIAN_CALENDAR, or NOVAS_ROMAN_CALENDAR.
[out]	year	[yr] Optional pointer to which to return the calendar year. It may be NULL if not required.

Returns

[1:366] The day-of-year index in the same timescale as the input date.

Since

1.4

Author

Attila Kovacs

See also

novas_day_of_week(), novas_jd_to_date()

References NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_JD_START_GREGORIAN, novas_jd_to_date(), and NOVAS_ROMAN_CALENDAR.

novas_jd_from_date()

double novas_jd_from_date	(	enum novas_calendar_type	calendar,
		int	year,
		int	month,
		int	day,
		double	hour )

Returns the Julian day for a given calendar date.

Input time value can be based on any astronomical time scale (UTC, UT1, TT, etc.) - output Julian date will have the same basis.

The input date is the conventional calendar date, affected by the Gregorian calendar reform of

1. Thus, the input date is for the Gregorian calendar for dates starting 15 October 1582, and for the Julian (Roman) calendar (introduced in 45 B.C.) for dates prior to that.

NOTES:

1. B.C. dates are indicated with years <=0 according to the astronomical and ISO 8601 convention, i.e., X B.C. as (1-X), so 45 B.C. as -44.

2. Added argument range checking in v1.3.0, returning NAN if the month or day are out of the normal range (for a leap year).

REFERENCES:

1. Fliegel, H. & Van Flandern, T. Comm. of the ACM, Vol. 11, No. 10, October 1968, p. 657.

Parameters

calendar	The type of calendar to use: NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_GREGORIAN_CALENDAR, or NOVAS_ROMAN_CALENDAR.
year	[yr] Calendar year. B.C. years can be simply represented as <=0, e.g. 1 B.C. as 0, and X B.C. as (1 - X).
month	[month] Calendar month [1:12]
day	[day] Day of month [1:31]
hour	[hr] Hour of day [0:24]

Returns

[day] the fractional Julian day for the input calendar date, ot NAN if the calendar is invalid or the month or day components are out of range.

Author

Attila Kovacs

Since

1.3

See also

novas_jd_to_date(), novas_get_time()

References NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_GREGORIAN_CALENDAR, NOVAS_JD_START_GREGORIAN, and NOVAS_ROMAN_CALENDAR.

novas_jd_to_date()

int novas_jd_to_date	(	double	tjd,
		enum novas_calendar_type	calendar,
		int *restrict	year,
		int *restrict	month,
		int *restrict	day,
		double *restrict	hour )

This function will compute a broken down date on the specified calendar for given the Julian day input.

Input Julian day can be based on any astronomical time scale (UTC, UT1, TT, etc.) - output time value will have same basis.

NOTES:

1. B.C. dates are indicated with years <=0 according to the astronomical and ISO 8601 convention, i.e., X B.C. as (1-X), so 45 B.C. as -44.

REFERENCES:

1. Fliegel, H. & Van Flandern, T. Comm. of the ACM, Vol. 11, No. 10, October 1968, p. 657.

Parameters

	tjd	[day] Julian day.
	calendar	The type of calendar to use: NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_GREGORIAN_CALENDAR, or NOVAS_ROMAN_CALENDAR.
[out]	year	[yr] Calendar year. B.C. years are represented as <=0, e.g. 1 B.C. as 0, and X B.C. as (1 - X). It may be NULL if not required.
[out]	month	[month] Calendar month [1:12]. It may be NULL if not required.
[out]	day	[day] Day of the month [1:31]. It may be NULL if not required.
[out]	hour	[h] Hour of day [0:24]. It may be NULL if not required.

Returns

0 if successful, or else -1 if the calendar is invalid (errno will be set to EINVAL).

Since

1.3

Author

Attila Kovacs

See also

novas_jd_from_date(), novas_set_time()

References NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_GREGORIAN_CALENDAR, NOVAS_JD_START_GREGORIAN, and NOVAS_ROMAN_CALENDAR.