Loading...
Searching...
No Matches
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
  The day-of-week index [1:7] in the same timescale as the input date. 1:Monday ... 7:Sunday, or else -1 if the input Julian Date is NAN.

Since
  1.4

Author
  Attila Kovacs

See also
  novas_day_of_year(), novas_jd_to_date()

References NOVAS_JD_J2000.

Referenced by supernovas::CalendarDate::day_of_week(), and supernovas::Time::day_of_week().

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

Referenced by supernovas::CalendarDate::day_of_year().

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

Referenced by supernovas::CalendarDate::CalendarDate(), julian_date(), and novas_parse_date_format().

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

Referenced by supernovas::CalendarDate::CalendarDate(), cal_date(), and novas_day_of_year().