duration

A duration is a positive or negative duration of time, written in ISO 8601 format like “PnYnMnDTnHnMnS” where each “n” is a number and fields may be omitted if they are zero.

All numbers must be integers, except for seconds which may be a decimal. If seconds is a decimal, then at least one digit must follow the decimal point. A negative duration is written with “-” as the first character, for example “-P60D”.

Canonical form omits all zero fields and writes no leading or trailing zeros, except for the zero duration which is written “P0Y”, for example “P1DT2H”, “PT30M”, or “PT4.5S”.

Non-canonical form allows zero fields, leading zeros, and for seconds to be written as a decimal even if it’s integer, for example “P06D”, “PT7.0S”, or “P0Y0M01DT06H00M00S”.

EXESS_MAX_DURATION_LENGTH

41U

The maximum length of a duration string from exess_write_duration()

struct ExessDuration

Duration of time.

To save space and to simplify arithmetic, this representation only stores two values: integer months, and decimal seconds (to nanosecond precision). These values are converted to and from the other fields during writing and reading. Years and months are stored as months, and days, hours, minutes, and seconds are stored as seconds.

The sign of all members must match, so a negative duration has all non-positive members, and a positive duration has all non-negative members.

int32_t months

Number of months.

int32_t seconds

Number of seconds.

int32_t nanoseconds

Number of nanoseconds.

ExessResult exess_read_duration(const char *str, ExessDuration *out)

Read a duration 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_duration(ExessDuration value, size_t buf_size, char *buf)

Write a canonical duration string.

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.