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.

ExessOrder exess_compare_duration(ExessDuration lhs, ExessDuration rhs)

Compare two durations.

Loosely speaking, a duration is considered less than another if it’s a shorter duration of time. However, note that two durations may not be comparable, since the relation between fields, such as the number of days in a month, varies at different times. Strictly speaking, two durations are comparable if adding them to any dateTime would produce results with the same ordering.

The ExessDuration representation condenses all fields into two values: months and seconds. When the two values are incomparable, a month is considered greater than any number of seconds.

Values with only months, or only seconds, are always comparable. Applications are encouraged to always use such values and never carry seconds into months or vice-versa.

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.

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.