Dates and times are a lot more complicated than we normally realize. This episodes explains durations.
You can specify a duration directly and it’s very simple now that you know how the date and time portion works. Just like how a capital letter T is used to signal the beginning of a time, a duration uses a capital letter P. The P stands for period. And there are two ways you can express a duration.
In the first method, you can include numeric values for a number of years, months, days, hours, minutes, and seconds just like how you would specify a date or time. But instead of a fixed number of digits, this form of a duration places another capital letter after each field. You can leave out fields if they’re zero or if you just don’t need them.
After the years, place a capital Y.
After the months, place a capital M.
After the days, place a capital D.
After the hours, place a capital H.
After the minutes, place a capital M.
And after the seconds, place a capital S.
You can instead refer to a duration of weeks and then use a capital letter W. You can’t combine weeks with the other fields though. So if you’re using weeks, then you can only use weeks.
Notice how both months and minutes both use a capital M? That’s okay because you still need the capital letter T to be placed before any time fields.
Using this form of a duration, if you want to express 10 hours and 30 minutes, then the proper way to do this is by writing:
PT10H30M.
What if you want a duration of 15 months, 1 day, and 12 hours? This is an interesting example because it shows a unique feature of durations that isn’t allowed in the normal DateTime representation. You’re allowed to exceed the normal range of fields in a duration. You can represent 15 months, 1 day, and 12 hours in a few different ways.
You can first convert 15 months into years and months like this:
P1Y3M1DT12H
Or you can just use the months as-is even though it goes beyond 12 like this:
P15M1DT12H
And you can still make use of fractional values at any point. Once you use fractional values though, there can be no more fields. You can combine the 12 hours into half a day like this:
P15M1.5D
The second form of expressing a duration uses the representation of a DateTime. Using what I just explained about the extra capital letters, you can still use all the date and time formatting you already know to represent a duration by just placing a capital P before it. So you can also represent 10 hours and 30 minutes like this:
PT10:30
Listen to the full episode for further explanation or you can also read the full transcript below.
Transcript
This episode continues the explanation of DateTime data types. I want to go back and explain a topic better that I introduced in episode 119, DateTimes, Part 2.
In that episode, I asked what 10:30 means. Is that a specific point in time or 10 hours and 30 minutes. And I said that it was up to you to decide. It wasn’t really a duration that I wanted to explain. In a way it was. But this episode will explain durations better than that. Real durations. I should not have said 10 hours and 30 minutes because that’s a real duration. The type of duration I was thinking about was an implied duration based on the precision of the DateTime. In other words, does 10:30 mean the exact point in time at 10 hours and 30 minutes into some day? Or does it cover the entire minute between 10:30 and 10:31? Normally, when I see something like 10:30, I think of the exact point in time.
The same thing applies to a date. Does 2020 refer to the moment on zero hours January 1st, 2020 only? Or does it refer to the entire year. I normally use dates like this to refer to the entire duration specified. But when you think about it, a DateTime is really just a value that can be as precise as you want by including ever smaller units from years, to months, to days, then to hours, minutes, seconds, and fractional values at any point along the way. So why should 2020 refer to an entire year but 10:30 refer to an instant in time? To be consistent, 10:30 should refer to an entire minute.
It may or may not refer to an entire minute. That’s the part that’s up to you to interpret. And we have normal expectations about what things should mean. But it should never refer to 10 hours and 30 minutes. At least not written in exactly that form. That’s the part that I got wrong.
How do you express a duration like 10 hours and 30 minutes? I’ll explain, right after this message from our sponsor.
Episode 119 explained one way to express an interval using a starting and ending DateTime separated by a forward slash. That also defines a duration between the starting and ending points. But what if you’re not so interested in specific start and end points and are more concerned about the amount of time between them?
You can specify a duration directly and it’s very simple now that you know how the date and time portion works. Just like how a capital letter T is used to signal the beginning of a time, a duration uses a capital letter P. The P stands for period. And there are two ways you can express a duration.
In the first method, you can include numeric values for a number of years, months, days, hours, minutes, and seconds just like how you would specify a date or time. But instead of a fixed number of digits, this form of a duration places another capital letter after each field. You can leave out fields if they’re zero or if you just don’t need them.
The capital letters are intuitive and expected.
◦ After the years, place a capital Y.
◦ After the months, place a capital M.
◦ After the days, place a capital D.
◦ After the hours, place a capital H.
◦ After the minutes, place a capital M.
◦ And after the seconds, place a capital S.
You can instead refer to a duration of weeks and then use a capital letter W. You can’t combine weeks with the other fields though. So if you’re using weeks, then you can only use weeks.
Notice how both months and minutes both use a capital M? That’s okay because you still need the capital letter T to be placed before any time fields.
Putting this together, if you want to express a duration of 10 hours and 30 minutes, then the proper way to do this is by writing PT10H30M.
What if you want a duration of 15 months, 1 day, and 12 hours? This is an interesting example because it shows a unique feature of durations that isn’t allowed in the normal DateTime representation. You’re allowed to exceed the normal range of fields in a duration. You can represent 15 months, 1 day, and 12 hours in a few different ways.
You can first convert 15 months into years and months like this:
◦ P1Y3M1DT12H
Or you can just use the months as-is even though it goes beyond 12 like this:
◦ P15M1DT12H
And you can still make use of fractional values at any point. Once you use fractional values though, there can be no more fields. You can combine the 12 hours into half a day like this:
◦ P15M1.5D
The second form of expressing a duration actually gets closer to when I said that 10:30 should never be used to represent a duration of 10 hours and 30 minutes. At least not without a slight change. Using what I just explained about the extra capital letters, you can still use all the date and time formatting you already know to represent a duration by just placing a capital P before it. So if you change the example to:
◦ PT10:30
Then this does now represent a 10 hour and 30 minute duration. Whenever, you use this form, just be aware that you have to go back to using leading zeros and fixed number of digits and the ability to exceed a field limit no longer applies. You have to stay within the valid ranges for each field.
Being able to specify duration directly is useful for repeating events.
Let me explain how to combine a DateTime with a duration first since it’s simple. Just use a forward slash to separate them just like how you would use a forward slash to separate two DateTime values to form the beginning and ending of an interval.
Use a DateTime, then a slash, and then a duration to specify an interval starting at the given Datetime. You can even go the other way and put the duration first, followed by a forward slash, and then the Datetime. This represents an interval that ends at the given Datetime.
To specify a repeating duration, use the capital letter R, followed by an optional number, and then a forward slash before the interval. If you don’t provide a number after the letter R, then the duration will repeat forever.
Here’s an example. Let’s say you want to express a meeting that should be held every week for 5 weeks beginning on July 1st, 2020 at 13 hours. You would write:
◦ R5/2020-07-01T13H/P1W
That says repeat 5 times, slash, starting at the date 2020-07-01, slash, with the duration of 1 week.
You might be used to a lot more flexibility than this in a modern calendar app. For example, how long is the meeting supposed to last? You’ll need to keep track of that with another duration. What if you want to repeat the meeting every other week? Well, the standard has you covered there. Just change the duration to be 2 weeks instead of 1 week. But if you want to meet every Monday and Wednesday each week, then you’re going to need to do a bit more work and keep track of that separately.