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

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
}