P5
A DESCRIPTION OF THE PROBLEM :
The JavaDoc for java.time.Duration.parse is inexact and has a few issues, which I am all reporting here:
1. The description of its effect is unclear.
2. The pattern is presented as an example.
3. ISO 8601 is referred to as "ISO-8601" (with a hyphen rather than a space).
4. What ISO calls "components" is called "sections".
5. It presents all sections as mandatory in some places.
The following solves these:
/**
* Constructs a {@code Duration} from a text string such as {@code P2DT12H}.
* <p>
* This will parse a textual representation of a duration, including the
* strings produced by {@code Duration.toString()}.
* The strings supported include a subset of ISO 8601 durations.
* Supported strings include between 1 and 4 components.
* Negative values and plus/minus signs are supported (although not part of the ISO 8601 standard).
* Supported strings follow the approximate pattern {@code P[nD][T[nH][nM][n[.nS]]]}
* (more precisely, in {@code Pattern} syntax, {@code [+-]?P([+-]?\d+D)?(T([+-]?\d+H)?([+-]?\d+M)?([+-]?\d+([.,]\d{0,9})?S)?)?}, case-insensitive).
* <p>
* 1 day is considered to be exactly 24 hours.
* <p>
* The string starts with an optional sign, denoted by the ASCII negative
* or positive symbol. If negative, the whole duration is negated.
* The ASCII letter "P" is next in upper or lower case.
* There are then from 1 to 4 components, each consisting of a number and a designator.
* The components have designators in ASCII of "D", "H", "M" and "S" for
* days, hours, minutes and seconds, accepted in upper or lower case.
* The components must occur in order. The time designator (ASCII letter "T") must occur before
* the first occurrence, if any, of an hour, minute or second component.
* At least one of the four components must be present, and if the time designator ("T") is present
* there must be at least one component after the "T".
* The number part of each component must consist of one or more ASCII digits (with an optional decimal point for seconds).
* The number may be prefixed by the ASCII negative or positive symbol.
* The number of days, hours and minutes must parse to a {@code long}.
* The number of seconds must parse to a {@code long} with optional fraction.
* The decimal point may be either a dot or a comma.
* The fractional part may have from zero to 9 digits.
* <p>
* Examples:
* <pre>
* "PT20.345S" -- parses as "20.345 seconds"
* "PT15M" -- parses as "15 minutes" (where a minute is 60 seconds)
* "PT10H" -- parses as "10 hours" (where an hour is 3,600 seconds)
* "P2D" -- parses as "2 days" (where a day is 24 hours or 86,400 seconds)
* "P2DT3H4M" -- parses as "2 days, 3 hours and 4 minutes"
* "PT-6H3M" -- parses as "-6 hours and +3 minutes"
* "-PT6H3M" -- parses as "-6 hours and -3 minutes"
* "-PT-6H+3M" -- parses as "+6 hours and -3 minutes" (357 minutes)
* </pre>
*
* @param text a textual duration, not null
* @return the parsed duration, not null
* @throws DateTimeParseException if the text cannot be parsed to a duration
*/
https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/time/Duration.html#parse(java.lang.CharSequence)
The JavaDoc for java.time.Duration.parse is inexact and has a few issues, which I am all reporting here:
1. The description of its effect is unclear.
2. The pattern is presented as an example.
3. ISO 8601 is referred to as "ISO-8601" (with a hyphen rather than a space).
4. What ISO calls "components" is called "sections".
5. It presents all sections as mandatory in some places.
The following solves these:
/**
* Constructs a {@code Duration} from a text string such as {@code P2DT12H}.
* <p>
* This will parse a textual representation of a duration, including the
* strings produced by {@code Duration.toString()}.
* The strings supported include a subset of ISO 8601 durations.
* Supported strings include between 1 and 4 components.
* Negative values and plus/minus signs are supported (although not part of the ISO 8601 standard).
* Supported strings follow the approximate pattern {@code P[nD][T[nH][nM][n[.nS]]]}
* (more precisely, in {@code Pattern} syntax, {@code [+-]?P([+-]?\d+D)?(T([+-]?\d+H)?([+-]?\d+M)?([+-]?\d+([.,]\d{0,9})?S)?)?}, case-insensitive).
* <p>
* 1 day is considered to be exactly 24 hours.
* <p>
* The string starts with an optional sign, denoted by the ASCII negative
* or positive symbol. If negative, the whole duration is negated.
* The ASCII letter "P" is next in upper or lower case.
* There are then from 1 to 4 components, each consisting of a number and a designator.
* The components have designators in ASCII of "D", "H", "M" and "S" for
* days, hours, minutes and seconds, accepted in upper or lower case.
* The components must occur in order. The time designator (ASCII letter "T") must occur before
* the first occurrence, if any, of an hour, minute or second component.
* At least one of the four components must be present, and if the time designator ("T") is present
* there must be at least one component after the "T".
* The number part of each component must consist of one or more ASCII digits (with an optional decimal point for seconds).
* The number may be prefixed by the ASCII negative or positive symbol.
* The number of days, hours and minutes must parse to a {@code long}.
* The number of seconds must parse to a {@code long} with optional fraction.
* The decimal point may be either a dot or a comma.
* The fractional part may have from zero to 9 digits.
* <p>
* Examples:
* <pre>
* "PT20.345S" -- parses as "20.345 seconds"
* "PT15M" -- parses as "15 minutes" (where a minute is 60 seconds)
* "PT10H" -- parses as "10 hours" (where an hour is 3,600 seconds)
* "P2D" -- parses as "2 days" (where a day is 24 hours or 86,400 seconds)
* "P2DT3H4M" -- parses as "2 days, 3 hours and 4 minutes"
* "PT-6H3M" -- parses as "-6 hours and +3 minutes"
* "-PT6H3M" -- parses as "-6 hours and -3 minutes"
* "-PT-6H+3M" -- parses as "+6 hours and -3 minutes" (357 minutes)
* </pre>
*
* @param text a textual duration, not null
* @return the parsed duration, not null
* @throws DateTimeParseException if the text cannot be parsed to a duration
*/
https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/time/Duration.html#parse(java.lang.CharSequence)