dateTime

A dateTime is a date and time, with an optional timezone offset.

Strings have the form YYYY-MM-DDTHH:MM:SS with an optional timezone suffix, 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” or “2001-02-03T12:13:14.56-06:00”

Canonical form only includes a decimal point if the number of seconds isn’t an integer. This implementation supports up to nanosecond resolution. Midnight at the end of the day, like “1999-12-31T24:00:00” is a valid value, equivalent to the start of the next day, like “2000-01-01T00:00:00”, which is the canonical form.

EXESS_MAX_DATE_TIME_LENGTH

37U

The maximum length of a dateTime string from exess_write_date_time()

struct ExessDateTime

Date and time.

This representation follows the syntax, except the timezone offset 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].

ExessTimezone zone

Timezone offset in quarter hours.

uint8_t hour

Hour: [0, 24].

uint8_t minute

Minute: [0, 59].

uint8_t second

Second: [0, 59].

uint32_t nanosecond

Nanosecond: [0, 999999999].

ExessDateTime exess_add_date_time_duration(ExessDateTime s, ExessDuration d)

Add a duration to a dateTime.

This advances or rewinds 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 zone 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.

ExessOrder exess_compare_date_time(ExessDateTime lhs, ExessDateTime rhs)

Compare two dateTimes.

Note that local and zoned dateTimes times may not be comparable. When the values aren’t comparable, this function arbitrarily chooses the local time to be lesser.

Returns:

Less than, equal to, or greater than zero if lhs is less than, equal to, or greater than rhs, respectively. Comparable and incomparable cases may also be distinguished, see ExessOrder for details.

ExessDateTime exess_date_time_to_utc(ExessDateTime datetime)

Convert a dateTime to UTC.

Returns:

The input converted to UTC if it has a timezone, otherwise the unmodified input.

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

Read a dateTime string after any leading whitespace.

Parameters:

  • str – String to read.

  • out – Parsed value, or zero on error.

Returns:

The count of characters read, and a status.

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

Write a dateTime string.

The written string is in canonical form, except that midnight at the end of the day (24:00:00) is written as-is. Note that this differs from the other write functions, which always write canonical form.

Parameters:

  • value – Value to write.

  • buf_size – 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.