![]() |
SuperNOVAS v1.3
The NOVAS C library, made better
|
Macros | |
#define | _DEFAULT_SOURCE |
strcasecmp() feature macro starting glibc 2.20 (2014-09-08) | |
Functions | |
double | novas_diff_tcb (const novas_timespec *t1, const novas_timespec *t2) |
double | novas_diff_tcg (const novas_timespec *t1, const novas_timespec *t2) |
double | novas_diff_time (const novas_timespec *t1, const novas_timespec *t2) |
double | novas_get_split_time (const novas_timespec *restrict time, enum novas_timescale timescale, long *restrict ijd) |
double | novas_get_time (const novas_timespec *restrict time, enum novas_timescale timescale) |
time_t | novas_get_unix_time (const novas_timespec *restrict time, long *restrict nanos) |
int | novas_iso_timestamp (const novas_timespec *restrict time, char *restrict dst, int maxlen) |
int | novas_offset_time (const novas_timespec *time, double seconds, novas_timespec *out) |
double | novas_parse_date (const char *restrict date, char **restrict tail) |
double | novas_parse_date_format (enum novas_calendar_type calendar, enum novas_date_format format, const char *restrict date, char **restrict tail) |
int | novas_print_timescale (enum novas_timescale scale, char *restrict buf) |
int | novas_set_split_time (enum novas_timescale timescale, long ijd, double fjd, int leap, double dut1, novas_timespec *restrict time) |
int | novas_set_time (enum novas_timescale timescale, double jd, int leap, double dut1, novas_timespec *restrict time) |
int | novas_set_unix_time (time_t unix_time, long nanos, int leap, double dut1, novas_timespec *restrict time) |
enum novas_timescale | novas_timescale_for_string (const char *restrict str) |
int | novas_timestamp (const novas_timespec *restrict time, enum novas_timescale scale, char *restrict dst, int maxlen) |
A set of SuperNOVAS routines to make handling of astronomical timescales and conversions among them easier.
double novas_diff_tcb | ( | const novas_timespec * | t1, |
const novas_timespec * | t2 ) |
Returns the Barycentric Coordinate Time (TCB) based time difference (t1 - t2) in days between two astronomical time specifications. TCB progresses slightly faster than time on Earth, at a rate about 1.6×10-8 higher, due to the lack of gravitational time dilation by the Earth or Sun.
t1 | First time |
t2 | Second time |
References novas_diff_time().
double novas_diff_tcg | ( | const novas_timespec * | t1, |
const novas_timespec * | t2 ) |
Returns the Geocentric Coordinate Time (TCG) based time difference (t1 - t2) in days between two astronomical time specifications. TCG progresses slightly faster than time on Earth, at a rate about 7×10-10 higher, due to the lack of gravitational time dilation by Earth. TCG is an appropriate time measure for a spacecraft that is in the proximity of the orbit of Earth, but far enough from Earth such that the relativistic effects of Earth's gravity can be ignored.
t1 | First time |
t2 | Second time |
References novas_diff_time().
double novas_diff_time | ( | const novas_timespec * | t1, |
const novas_timespec * | t2 ) |
Returns the Terrestrial Time (TT) based time difference (t1 - t2) in days between two astronomical time specifications.
t1 | First time |
t2 | Second time |
References novas_timespec::fjd_tt, and novas_timespec::ijd_tt.
double novas_get_split_time | ( | const novas_timespec *restrict | time, |
enum novas_timescale | timescale, | ||
long *restrict | ijd ) |
Returns the fractional Julian date of an astronomical time in the specified timescale, as an integer and fractional part. The two-component split of the time allows for absolute precisions at the picosecond level, as opposed to novas_set_time()
, whose precision is limited to a few microseconds typically.
The accuracy of Barycentric Time measures (TDB and TCB) relative to other time measures is limited by the precision of the tbd2tt()
implemenation, to around 10 μs.
REFERENCES:
time | Pointer to the astronomical time specification data structure. | |
timescale | The astronomical time scale in which the returned Julian Date is to be provided | |
[out] | ijd | [day] The integer part of the Julian date in the requested timescale. It may be NULL if not required. |
References NOVAS_GPS, NOVAS_TAI, NOVAS_TCB, NOVAS_TCG, NOVAS_TDB, NOVAS_TT, NOVAS_UT1, and NOVAS_UTC.
double novas_get_time | ( | const novas_timespec *restrict | time, |
enum novas_timescale | timescale ) |
Returns the fractional Julian date of an astronomical time in the specified timescale. The returned time is accurate to a few μs (microsecond) due to the inherent precision of the double-precision result. For higher precision applications you may use novas_get_split_time()
instead, which has an inherent accuracy at the picosecond level.
time | Pointer to the astronomical time specification data structure. |
timescale | The astronomical time scale in which the returned Julian Date is to be provided |
References novas_get_split_time().
time_t novas_get_unix_time | ( | const novas_timespec *restrict | time, |
long *restrict | nanos ) |
Returns the UNIX time for an astronomical time instant.
time | Pointer to the astronomical time specification data structure. | |
[out] | nanos | [ns] UTC sub-second component. It may be NULL if not required. |
References novas_get_split_time(), and NOVAS_UTC.
int novas_iso_timestamp | ( | const novas_timespec *restrict | time, |
char *restrict | dst, | ||
int | maxlen ) |
Prints a UTC-based ISO timestamp to millisecond precision to the specified string buffer. E.g.:
2025-01-26T21:32:49.701Z
NOTES:
time | Pointer to the astronomical time specification data structure. | |
[out] | dst | Output string buffer. At least 25 bytes are required for a complete timestamp with termination. |
maxlen | The maximum number of characters that can be printed into the output buffer, including the string termination. If the full ISO timestamp is longer than maxlen , then it will be truncated to fit in the allotted space, including a termination character. |
maxlen - 1
.References novas_get_split_time(), and NOVAS_UTC.
int novas_offset_time | ( | const novas_timespec * | time, |
double | seconds, | ||
novas_timespec * | out ) |
Increments the astrometric time by a given amount.
time | Original time specification | |
seconds | [s] Seconds to add to the original | |
[out] | out | New incremented time specification. It may be the same as the input. |
References novas_timespec::fjd_tt, and novas_timespec::ijd_tt.
double novas_parse_date | ( | const char *restrict | date, |
char **restrict | tail ) |
Parses a date/time string into a Julian date specification. Typically the date may be an ISO date specification, but with some added flexibility. The date must be YMD-type with full year, followed the month (numerical or name or 3-letter abbreviation), and the day. The components may be separated by dash -
, underscore _
, dot .
, slash '/', or spaces/tabs, or any combination thereof. The date may be followed by a time specification in HMS format, separated from the date by the letter T
or t
, or spaces, comma ,
, or semicolon ;
, or underscore _
or a combination thereof. Finally, the time may be followed by the letter Z
, or z
(for UTC) or else {+/-}HH[:[MM]] time zone specification.
For example:
2025-01-26 2025 January 26 2025_Jan_26 2025-01-26T19:33:08Z 2025.01.26T19:33:08 2025 1 26 19h33m28.113 2025/1/26 19:33:28+02 2025-01-26T19:33:28-0600 2025 Jan 26 19:33:28+05:30
are all valid dates that can be parsed.
NOTES:
This function uses Gregorian dates since their introduction on 1582 October 15, and Julian/Roman datew before that, as was the convention of the time. I.e., the day before of the introduction of the Gregorian calendar reform is 1582 October 4.
date | The date specification, possibly including time and timezone, in a standard format. | |
[out] | tail | (optional) If not NULL it will be set to the next character in the string after the parsed time. The parsing will consume empty space characters after the time specification also, returning a pointer to the next token after. |
References NOVAS_ASTRONOMICAL_CALENDAR, novas_parse_date_format(), and NOVAS_YMD.
double novas_parse_date_format | ( | enum novas_calendar_type | calendar, |
enum novas_date_format | format, | ||
const char *restrict | date, | ||
char **restrict | tail ) |
Parses a calndar date/time string, expressed in the specified type of calendar, into a Julian day (JD). The date must be composed of a full year (e.g. 2025), a month (numerical or name or 3-letter abbreviation, e.g. "01", "1", "January", or "Jan"), and a day (e.g. "08" or "8"). The components may be separated by dash -
, underscore _
, dot .
, slash '/', or spaces/tabs, or any combination thereof. The components will be parsed in the specified order.
The date may be followed by a time specification in HMS format, separated from the date by the letter T
or t
, or spaces, comma ,
, or semicolon ;
or underscore '_', or a combination thereof. Finally, the time may be followed by the letter Z
, or z
(for UTC) or else by a {+/-}HH[:[MM]] time zone specification.
For example, for format
NOVAS_YMD, all of the following strings may specify the date:
2025-01-26 2025 January 26 2025_Jan_26 2025-01-26T19:33:08Z 2025.01.26T19:33:08 2025 1 26 19h33m28.113 2025/1/26 19:33:28+02 2025-01-26T19:33:28-0600 2025 Jan 26 19:33:28+05:30
are all valid dates that can be parsed.
If your date format cannot be parsed with this function, you may parse it with your own function into year, month, day, and decimal hour-of-day components, and use julian_date() with those.
NOTES:
calendar | The type of calendar to use: NOVAS_ASTRONOMICAL_CALENDAR, NOVAS_GREGORIAN_CALENDAR, or NOVAS_ROMAN_CALENDAR. | |
format | Expected order of date components: NOVAS_YMD, NOVAS_DMY, or NOVAS_MDY. | |
date | The date specification, possibly including time and timezone, in the specified standard format. | |
[out] | tail | (optional) If not NULL it will be set to the next character in the string after the parsed time. The parsing will consume empty space characters after the time specification also, returning a pointer to the next token after. |
References novas_debug(), NOVAS_DEBUG_OFF, NOVAS_DMY, novas_get_debug_mode(), novas_jd_from_date(), NOVAS_MDY, novas_parse_hms(), and NOVAS_YMD.
int novas_print_timescale | ( | enum novas_timescale | scale, |
char *restrict | buf ) |
Prints the standard string representation of the timescale to the specified buffer. The string is terminated after. E.g. "UTC", or "TAI". It will print dates in the Gregorian calendar, which was introduced in was introduced on 15 October 1582 only. Thus the
scale | The timescale |
buf | String in which to print. It should have at least 4-bytes of available storage. |
References NOVAS_GPS, NOVAS_TAI, NOVAS_TCB, NOVAS_TCG, NOVAS_TDB, NOVAS_TT, NOVAS_UT1, and NOVAS_UTC.
int novas_set_split_time | ( | enum novas_timescale | timescale, |
long | ijd, | ||
double | fjd, | ||
int | leap, | ||
double | dut1, | ||
novas_timespec *restrict | time ) |
Sets an astronomical time to the split Julian Date value, defined in the specified timescale. The split into the integer and fractional parts can be done in any convenient way. The highest precision is reached if the fractional part is ≤ 1 day. In that case, the time may be specified to picosecond accuracy, if needed.
The accuracy of Barycentric Time measures (TDB and TCB) relative to other time measures is limited by the precision of tbd2tt()
implementation, to around 10 μs.
REFERENCES:
timescale | The astronomical time scale in which the Julian Date is given | |
ijd | [day] integer part of the Julian day in the specified timescale | |
fjd | [day] fractional part Julian day value in the specified timescale | |
leap | [s] Leap seconds, e.g. as published by IERS Bulletin C. | |
dut1 | [s] UT1-UTC time difference, e.g. as published in IERS Bulletin A. | |
[out] | time | Pointer to the data structure that uniquely defines the astronomical time for all applications. |
References NOVAS_GPS, NOVAS_TAI, NOVAS_TCB, NOVAS_TCG, NOVAS_TDB, NOVAS_TT, NOVAS_UT1, NOVAS_UTC, and tt2tdb().
int novas_set_time | ( | enum novas_timescale | timescale, |
double | jd, | ||
int | leap, | ||
double | dut1, | ||
novas_timespec *restrict | time ) |
Sets an astronomical time to the fractional Julian Date value, defined in the specified timescale. The time set this way is accurate to a few μs (microseconds) due to the inherent precision of the double-precision argument. For higher precision applications you may use novas_set_split_time()
instead, which has an inherent accuracy at the picosecond level.
timescale | The astronomical time scale in which the Julian Date is given | |
jd | [day] Julian day value in the specified timescale | |
leap | [s] Leap seconds, e.g. as published by IERS Bulletin C. | |
dut1 | [s] UT1-UTC time difference, e.g. as published in IERS Bulletin A. | |
[out] | time | Pointer to the data structure that uniquely defines the astronomical time for all applications. |
References novas_set_split_time().
int novas_set_unix_time | ( | time_t | unix_time, |
long | nanos, | ||
int | leap, | ||
double | dut1, | ||
novas_timespec *restrict | time ) |
Sets an astronomical time to a UNIX time value. UNIX time is defined as UTC seconds measured since 0 UTC, 1 Jan 1970 (the start of the UNIX era). Specifying time this way supports precisions to the nanoseconds level by construct. Specifying UNIX time in split seconds and nanoseconds is a common way CLIB handles precision time, e.g. with struct timespec
and functions like clock_gettime()
(see time.h
).
unix_time | [s] UNIX time (UTC) seconds | |
nanos | [ns] UTC sub-second component | |
leap | [s] Leap seconds, e.g. as published by IERS Bulletin C. | |
dut1 | [s] UT1-UTC time difference, e.g. as published in IERS Bulletin A. | |
[out] | time | Pointer to the data structure that uniquely defines the astronomical time for all applications. |
References novas_set_split_time(), and NOVAS_UTC.
enum novas_timescale novas_timescale_for_string | ( | const char *restrict | str | ) |
Returns the timescale constant for a string that denotes the timescale in with a standard abbreviation (case insensitive). The following values are recognised: "UTC", "UT", "UT0", "UT1", "GMT", "TAI", "GPS", "TT", "ET", "TCG", "TCB", "TDB".
str | String specifying an astronomical timescale |
References NOVAS_GPS, NOVAS_TAI, NOVAS_TCB, NOVAS_TCG, NOVAS_TDB, NOVAS_TT, NOVAS_UT1, and NOVAS_UTC.
int novas_timestamp | ( | const novas_timespec *restrict | time, |
enum novas_timescale | scale, | ||
char *restrict | dst, | ||
int | maxlen ) |
Prints a timestamp to millisecond precision in the specified timescale to the specified string buffer. E.g.:
2025-01-26T21:32:49.701 TAI
NOTES:
The timestamp uses the astronomical date. That is Gregorian dates after the Gregorian calendar reform of 15 October 1582, and Julian/Roman dates prior to that.
time | Pointer to the astronomical time specification data structure. | |
scale | The timescale to use. | |
[out] | dst | Output string buffer. At least 28 bytes are required for a complete timestamp with termination. |
maxlen | The maximum number of characters that can be printed into the output buffer, including the string termination. If the full ISO timestamp is longer than maxlen , then it will be truncated to fit in the allotted space, including a termination character. |
maxlen - 1
.References novas_get_split_time(), and novas_print_timescale().