# parse

Parses a ISO 8601 duration string as a DateTimePeriod.

If the time components are absent or equal to zero, returns a DatePeriod.

Note that the ISO 8601 duration is not the same as Duration, but instead includes the date components, like DateTimePeriod does.

Examples of durations in the ISO 8601 format:

`P1Y40D`

is one year and 40 days`-P1DT1H`

is minus (one day and one hour)`P1DT-1H`

is one day minus one hour`-PT0.000000001S`

is minus one nanosecond

The format is defined as follows:

First, optionally, a

`-`

or`+`

. If`-`

is present, the whole period after the`-`

is negated:`-P-2M1D`

is the same as`P2M-1D`

.Then, the letter

`P`

.Optionally, the number of years, followed by

`Y`

.Optionally, the number of months, followed by

`M`

.Optionally, the number of weeks, followed by

`W`

.Optionally, the number of days, followed by

`D`

.The string can end here if there are no more time components. If there are time components, the letter

`T`

is required.Optionally, the number of hours, followed by

`H`

.Optionally, the number of minutes, followed by

`M`

.Optionally, the number of seconds, followed by

`S`

. Seconds can optionally have a fractional part with up to nine digits. The fractional part is separated with a`.`

.

An explicit `+`

or `-`

sign can be prepended to any number. `-`

means that the number is negative, and `+`

has no effect.

See ISO-8601-1:2019, 5.5.2.2a) and 5.5.2.2b). We combine the two formats into one by allowing the number of weeks to go after the number of months and before the number of days.

#### Throws

if the text cannot be parsed or the boundaries of DateTimePeriod are exceeded.

#### Samples

```
import kotlinx.datetime.*
import kotlin.test.*
import kotlin.time.Duration.Companion.days
import kotlin.time.Duration.Companion.minutes
fun main() {
//sampleStart
// Parsing a string representation of a DateTimePeriod
with(DateTimePeriod.parse("P1Y2M3DT4H5M6.000000007S")) {
check(years == 1)
check(months == 2)
check(days == 3)
check(hours == 4)
check(minutes == 5)
check(seconds == 6)
check(nanoseconds == 7)
}
with(DateTimePeriod.parse("P14M-16DT5H")) {
check(years == 1)
check(months == 2)
check(days == -16)
check(hours == 5)
}
with(DateTimePeriod.parse("-P2M16DT5H")) {
check(years == 0)
check(months == -2)
check(days == -16)
check(hours == -5)
}
//sampleEnd
}
```