Duration

An xsd: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 is integer, for example “P06D”, “PT7.0S”, or “P0Y0M01DT06H00M00S”.

struct ExessDuration

A duration of time (xsd:duration value).

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
int32_t seconds
int32_t nanoseconds
ExessResult exess_read_duration(ExessDuration *out, const char *str)

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

Write a canonical xsd:duration 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_DURATION_LENGTH

The maximum length of an xsd:duration string from exess_write_duration(), 41.