Examples #
Here are some examples of Custom durations that have been requested. In Green is what would be used as the custom durations syntax.
Year options: 5 Years – P5Y | 3 Years – P3Y | 2 Years – P2Y
Month options: 9 Months – P9M | 3 Months – P3M | 2 Months – P2M
Week options: 16 weeks – P16W | 14 weeks – P14W | 12 weeks – P12W | 10 weeks – P10W | 8 weeks – P8W | 6 weeks – P6W
Day options: 10 Days – P10D | 6 Days – P6D | 5 Days – P5D | 4 Days – P4D | 3 Days – P3D | 2 Days – P2D
More Information on Custom Durations #
Durations define the amount of intervening time in a time interval and are represented by the format P[n]Y[n]M[n]DT[n]H[n]M[n]S or P[n]W as shown on the aside. In these representations, the [n] is replaced by the value for each of the date and time elements that follow the [n]. Leading zeros are not required, but the maximum number of digits for each element should be agreed to by the communicating parties. The capital letters P, Y, M, W, D, T, H, M, and S are designators for each of the date and time elements and are not replaced.
- P is the duration designator (for period) placed at the start of the duration representation.
- Y is the year designator that follows the value for the number of calendar years.
- M is the month designator that follows the value for the number of calendar months.
- W is the week designator that follows the value for the number of weeks.
- D is the day designator that follows the value for the number of calendar days.
- T is the time designator that precedes the time components of the representation.
- H is the hour designator that follows the value for the number of hours.
- M is the minute designator that follows the value for the number of minutes.
- S is the second designator that follows the value for the number of seconds.
For example, “P3Y6M4DT12H30M5S” represents a duration of “three years, six months, four days, twelve hours, thirty minutes, and five seconds”.
Date and time elements including their designator may be omitted if their value is zero, and lower-order elements may also be omitted for reduced precision. For example, “P23DT23H” and “P4Y” are both acceptable duration representations. However, at least one element must be present, thus “P” is not a valid representation for a duration of 0 seconds. “PT0S” or “P0D”, however, are both valid and represent the same duration.
To resolve ambiguity, “P1M” is a one-month duration and “PT1M” is a one-minute duration (note the time designator, T, that precedes the time value). The smallest value used may also have a decimal fraction, as in “P0.5Y” to indicate half a year. This decimal fraction may be specified with either a comma or a full stop, as in “P0,5Y” or “P0.5Y”. The standard does not prohibit date and time values in a duration representation from exceeding their “carry over points” except as noted below. Thus, “PT36H” could be used as well as “P1DT12H” for representing the same duration. But keep in mind that “PT36H” is not the same as “P1DT12H” when switching from or to Daylight saving time.
Alternatively, a format for duration based on combined date and time representations may be used by agreement between the communicating parties either in the basic format PYYYYMMDDThhmmss or in the extended format P[YYYY]-[MM]-[DD]T[hh]:[mm]:[ss]. For example, the first duration shown above would be “P0003-06-04T12:30:05”. However, individual date and time values cannot exceed their moduli (e.g. a value of 13 for the month or 25 for the hour would not be permissible).
The standard describes a duration as part of time intervals, which are discussed in the next section. The duration format on its own is ambiguous regarding the total number of days in a calendar year and calendar month. The number of seconds in a calendar day is also ambiguous because of leap seconds. For example “P1M” on its own could be 28, 29, 30, or 31 days. There is no ambiguity when used in a time interval. Using example “P2M” duration of two calendar months:
- interval 2003-02-15T00:00:00Z/P2M ends two calendar months later at 2003-04-15T00:00:00Z which is 59 days later
- interval 2003-07-15T00:00:00Z/P2M ends two calendar months later at 2003-09-15T00:00:00Z which is 62 days later
The duration format (or a subset thereof) is widely used independent of time intervals, as with the Java 8 Duration class which supports a subset of the duration format.
For more help on this subject contact bowlslink@bowls.com.au