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.

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.