asdf/core/time.h - Time tag operations

Data type and extension for the stsci.edu/schemas/asdf/time/time schema

Types

enum asdf_time_format_t

The representation format of a time.

These correspond to the astropy time formats and the schema’s format / base_format enums. The values from ASDF_TIME_FORMAT_BYEAR_STR onward are the schema’s other_format values, which are valid only in base_format on the wire; see asdf_time_t format for how the two collapse into a single effective format.

enumerator ASDF_TIME_FORMAT_ISO = 0

ISO 8601 date-time, YYYY-MM-DDTHH:MM:SS.sss... (the default)

enumerator ASDF_TIME_FORMAT_YDAY

Year, day-of-year and time, YYYY:DOY:HH:MM:SS.sss...

enumerator ASDF_TIME_FORMAT_BYEAR

Besselian epoch year, e.g. B1950.0

enumerator ASDF_TIME_FORMAT_JYEAR

Julian epoch year, e.g. J2000.0

enumerator ASDF_TIME_FORMAT_DECIMALYEAR

Decimal year, integer values being the start of the year

enumerator ASDF_TIME_FORMAT_JD

Julian Date: days since the start of the Julian period

enumerator ASDF_TIME_FORMAT_MJD

Modified Julian Date: days since 1858-11-17 00:00

enumerator ASDF_TIME_FORMAT_GPS

GPS time: seconds from 1980-01-06 00:00:00 UTC

enumerator ASDF_TIME_FORMAT_UNIX

Unix time: seconds from 1970-01-01 00:00:00 UTC, ignoring leap seconds

enumerator ASDF_TIME_FORMAT_UTIME

UT seconds from 1979-01-01 00:00:00 UTC, ignoring leap seconds

enumerator ASDF_TIME_FORMAT_TAI_SECONDS

SI seconds from 1958-01-01 00:00:00, including leap seconds (TAI)

enumerator ASDF_TIME_FORMAT_CXCSEC

Chandra X-ray Center seconds from 1998-01-01 00:00:00 TT

enumerator ASDF_TIME_FORMAT_GALEXSEC

GALEX time: seconds from 1980-01-06 00:00:00 UTC

enumerator ASDF_TIME_FORMAT_UNIX_TAI

SI seconds from 1970-01-01 00:00:00 TAI

enumerator ASDF_TIME_FORMAT_RESERVED1

Reserved; not a usable format

enumerator ASDF_TIME_FORMAT_BYEAR_STR

Besselian epoch string form, e.g. B1950.0

enumerator ASDF_TIME_FORMAT_DATETIME

A Python datetime.datetime (naive or timezone-aware)

enumerator ASDF_TIME_FORMAT_FITS

FITS date-time string; permits a signed five-digit “long” year

enumerator ASDF_TIME_FORMAT_ISOT

ISO 8601 with a literal T date/time separator

enumerator ASDF_TIME_FORMAT_JYEAR_STR

Julian epoch string form, e.g. J2000.0

enumerator ASDF_TIME_FORMAT_PLOT_DATE

matplotlib ordinal: days from 0001-01-01 00:00:00 UTC plus one

enumerator ASDF_TIME_FORMAT_YMDHMS

Year/month/day/hour/minute/second fields

enumerator ASDF_TIME_FORMAT_DATETIME64

NumPy datetime64

enum asdf_time_scale_t

The time scale (time standard), as in the schema’s scale field.

enumerator ASDF_TIME_SCALE_UTC = 0

Coordinated Universal Time (the default scale)

enumerator ASDF_TIME_SCALE_TAI

International Atomic Time

enumerator ASDF_TIME_SCALE_TCB

Barycentric Coordinate Time

enumerator ASDF_TIME_SCALE_TCG

Geocentric Coordinate Time

enumerator ASDF_TIME_SCALE_TDB

Barycentric Dynamical Time

enumerator ASDF_TIME_SCALE_TT

Terrestrial Time

enumerator ASDF_TIME_SCALE_UT1

Universal Time (UT1)

struct asdf_time_location_t

Observer location, used by location-sensitive scales such as tdb.

struct asdf_time_info_t

Best-effort calendar representation of a parsed time

These fields are computed from value / format / scale purely for convenience. The authoritative instant is always the value, format and scale, which libasdf preserves verbatim and round-trips losslessly; only this derived representation is approximate.

Warning

For any time not on the UTC scale, i.e. scale other than ASDF_TIME_SCALE_UTC, and the atomic-scale formats gps, unix_tai, cxcsec and tai_seconds, these fields ignore leap seconds. libasdf has no leap-second table, so it does not apply the TAI/TT-to-UTC offsets.

The computed calendar reading is therefore in the format’s own timescale, off from UTC by the relevant offset. The tdb, ut1, tcb and tcg scales need still more external data and are likewise approximate.

Consumers needing an exact UTC instant for a non-UTC-scale time should convert the raw value / format / scale themselves (e.g. via ERFA or astropy).

struct timespec ts

Seconds + nanoseconds from the Unix epoch (approximate; see above)

struct tm tm

Derived calendar fields (approximate; see above)

struct asdf_time_t

A single instant in time, as read from or written to a time/time tag.

The instant is defined by value together with format and scale; info is a derived, best-effort calendar representation for convenience.

char *value

The time value, exactly as it appears (or will appear) in the file.

asdf_time_info_t info

Derived calendar representation; best-effort and, for non-UTC scales, approximate. See asdf_time_info_t for the leap-second caveat.

asdf_time_format_t format

The effective (real) format of the time.

This may be any format, including one of the schema’s other_format values (e.g. fits, isot, plot_date) which the schema only permits in the base_format field on the wire. On deserialization the format and base_format keys are collapsed into this single effective format (base_format overrides format when present); on serialization the wire format / base_format split is derived back from it.

asdf_time_scale_t scale

The time scale. A non-UTC scale means the derived info fields are approximate (leap seconds are not applied); see asdf_time_info_t.

asdf_time_location_t location

Observer location; used only by location-sensitive scales (e.g. tdb).

Accessors

bool asdf_is_time(asdf_file_t *file, const char *path)

Test whether the value at path in the tree is a time/time object

Parameters:
Returns:

true if the value exists and is a time, otherwise false

asdf_value_err_t asdf_get_time(asdf_file_t *file, const char *path, asdf_time_t **out)

Get an asdf_time_t* out of the ASDF tree

The returned object is owned by the caller and must be freed with asdf_time_destroy.

Parameters:
Returns:

ASDF_VALUE_OK if the value exists and is a time, otherwise ASDF_VALUE_ERR_NOT_FOUND or ASDF_VALUE_ERR_TYPE_MISMATCH.

asdf_value_err_t asdf_set_time(asdf_file_t *file, const char *path, const asdf_time_t *time)

Store an asdf_time_t* at a path in the ASDF tree

Only the value, format, scale and location fields need be populated; the derived asdf_time_info_t info is not required for writing.

Parameters:
Returns:

ASDF_VALUE_OK on success, otherwise an error code

bool asdf_value_is_time(asdf_value_t *value)

Test whether a generic asdf_value_t* is a time/time object

Parameters:
Returns:

true if value is a time, otherwise false

asdf_value_err_t asdf_value_as_time(asdf_value_t *value, asdf_time_t **out)

Interpret a generic asdf_value_t* as a time value, if possible

The returned object is owned by the caller and must be freed with asdf_time_destroy.

Parameters:
Returns:

ASDF_VALUE_OK if value is a time, otherwise ASDF_VALUE_ERR_TYPE_MISMATCH.

void asdf_time_destroy(asdf_time_t *time)

Free an asdf_time_t* returned by asdf_get_time or asdf_value_as_time

Parameters:

Parsing and formatting

int asdf_time_parse(asdf_time_t *time)

Parse time’s value (according to its format) into the derived asdf_time_info_t info fields.

This is called automatically during deserialization; it may be called again after changing value or format. See asdf_time_info_t for the accuracy caveat on non-UTC scales.

Parameters:

  • time – The time to parse; its info is filled in on success.

Returns:

0 on success, or -1 on failure (e.g. an unsupported or unparseable value).

const char *asdf_time_format_string(asdf_time_format_t format)

Return the schema string name of a time format (e.g. "iso", "jd").

Parameters:

  • format – A time format.

Returns:

The format’s name, or NULL if format is out of range or has no string representation.

Defines

ASDF_CORE_TIME_TAG_BASE

Tag URI prefix for time objects; a version is appended (e.g. "1.4.0").

ASDF_CORE_TIME_TAG

The time tag written by libasdf, and the newest version it reads.

Older versions (ASDF_CORE_TIME_TAG_BASE "1.x.0") are also recognized when reading; see the ASDF_REGISTER_EXTENSION call in time.c.

ASDF_TIME_TIMESTR_MAXLEN

Maximum length in bytes of a time asdf_time_t value string.