Datetime

An xsd:datetime is a date and time in either UTC or local time.

Strings have the form YYYY-MM-DDTHH:MM:SS with at least 4 year digits (negative or positive), and all other fields positive two-digit integers except seconds which may be a decimal, for example “2001-02-03T12:13:14.56”. Nanosecond precision is supported.

A local datetime has no suffix, a datetime with a time zone is always in UTC, and is written with a “Z” suffix, for example 2001-02-03T12:13:14Z.

Canonical form only includes a decimal point if the number of seconds is not an integer.

This implementation supports up to nanosecond resolution.

struct ExessDateTime

A date and time (xsd:dateTime value).

This representation follows the syntax, except the UTC flag is stored between the date and time for more efficient packing.

int16_t year

Year: any positive or negative value.

uint8_t month

Month: [1, 12].

uint8_t day

Day: [1, 31].

uint8_t is_utc

True if this is UTC (not local) time.

uint8_t hour

Hour: [0, 23].

uint8_t minute

Minute: [0, 59].

uint8_t second

Second: [0, 59].

uint32_t nanosecond

Nanosecond: [0, 999999999].

int exess_datetime_compare(ExessDateTime lhs, ExessDateTime rhs)

Compare two datetimes.

Note that datetimes are not totally ordered since the order between UTC and local times can be indeterminate. When comparing UTC and local times, if there is a difference of more than 14 hours, then the comparison is determinate (according to the XSD specification). Otherwise, this function will arbitrarily order the local time first.

Returns

-1, 0, or 1 if lhs is less than, equal to, or greater than rhs, respectively.

ExessDateTime exess_add_datetime_duration(ExessDateTime s, ExessDuration d)

Add a duration to a datetime.

This advances or rewinds the datetime by the given duration, depending on whether the duration is positive or negative.

If underflow or overflow occur, then this will return an infinite value. A positive infinity has all fields at maximum, and a negative infinity has all fields at minimum, except is_utc which is preserved from the input (so infinities are comparable with the values they came from). Since 0 and 255 are never valid months, these can be tested for by checking if the year and month are INT16_MIN and 0, or INT16_MAX and INT8_MAX.

Returns

s + d, or an infinite past or infinite future if underflow or overflow occurs.

ExessResult exess_read_datetime(ExessDateTime *out, const char *str)

Read an xsd:dateTime string after any leading whitespace.

Parameters

  • out – Set to the parsed value, or zero on error.

  • str – String input.

Returns

The count of characters read, and a status code.

ExessResult exess_write_datetime(ExessDateTime value, size_t buf_size, char *buf)

Write a canonical xsd:datetime string.

Parameters

  • value – Value to write.

  • buf_size – The size of buf in bytes.

  • buf – Output buffer, or null to only measure.

Returns

ExessStatus.EXESS_SUCCESS on success, ExessStatus.EXESS_NO_SPACE if the buffer is too small, or ExessStatus.EXESS_BAD_VALUE if the value is invalid.

EXESS_MAX_DATETIME_LENGTH

The maximum length of an xsd:dateTime string from exess_write_datetime(), 32.