# datetime 'UTCLeapSeconds', 2 second difference across leap sec boundary

13 views (last 30 days)
James Tursa on 20 Mar 2015
Commented: Peter Perkins on 31 May 2018
I was recently made aware of the leap second capability in the new datetime class of R2014b, so I did some simple tests and did not get the expected results. Am I doing something wrong or is the leap second adjustment wrong?
1st case is two dates surrounding a June 30 that did NOT have a leap second, 2013, and using the 'UTC' for TimeZone:
>> t3 = datetime(2013,6,30,0,0,0)
t3 =
30-Jun-2013 00:00:00
>> t3.TimeZone = 'UTC'
t3 =
30-Jun-2013 00:00:00
>> t4 = datetime(2013,7,2,0,0,0)
t4 =
02-Jul-2013 00:00:00
>> t4.TimeZone = 'UTC'
t4 =
02-Jul-2013 00:00:00
>> seconds(t4-t3) - 2*86400
ans =
0
Exactly two 86400 second days as expected. All well and good.
2nd case is two dates surrounding a June 30 that DID have a leap second, 2012, and using the 'UTCLeapSeconds' for TimeZone:
>> t1 = datetime(2012,6,30,0,0,0)
t1 =
30-Jun-2012 00:00:00
>> t1.TimeZone = 'UTCLeapSeconds'
t1 =
2012-06-30T00:00:24.000Z
>> t2 = datetime(2012,7,2,0,0,0)
t2 =
02-Jul-2012 00:00:00
>> t2.TimeZone = 'UTCLeapSeconds'
t2 =
2012-07-02T00:00:25.000Z
>> seconds(t2-t1) - 2*86400
ans =
2
So the 24.000 and 25.000 that are showing up in the date displays match the total number of leap seconds that have been applied through those dates (e.g., see http://en.wikipedia.org/wiki/Leap_second). So that seems to match. But when I look at the difference I get 2 seconds instead of the expected 1 second across this applied leap second boundary. What am I missing here? Am I building the dates or applying the UTCLeapSeconds TimeZone incorrectly? Or what?
3rd case is two dates surrounding a June 30 that DID have a leap second, 2015, but is announced in the future, again using the 'UTCLeapSeconds' for TimeZone:
>> t5 = datetime(2015,6,30,0,0,0)
t5 =
30-Jun-2015 00:00:00
>> t5.TimeZone = 'UTCLeapSeconds'
t5 =
2015-06-30T00:00:25.000Z
>> t6 = datetime(2015,7,2,0,0,0)
t6 =
02-Jul-2015 00:00:00
>> t6.TimeZone = 'UTCLeapSeconds'
t6 =
2015-07-02T00:00:25.000Z
>> seconds(t6-t5) - 2*86400
ans =
0
So the announced leap second is not accounted for here (obvious from looking at the 25.000 in the t6 date instead of the expected 26.000). So what is the process for keeping the datetime function up-to-date for leap second adjustments? This needs to be a table look up of some sort in the background, so how does one get/keep this updated? I didn't see anything in the doc that mentions this.

Peter Perkins on 22 Mar 2015
Edited: Peter Perkins on 22 Mar 2015
James, in the second instance, you're subtracting 2012-06-30T00:00:24.000Z from 2012-07-02T00:00:25.000Z. There really is 86401+86400+1 seconds difference, i.e. 2*86400 + 2, because of the one leap second and the 1s diffference in the times of day. I think the confusion stems from the diff between what you did and this:
>> t1 = datetime(2012,6,30,0,0,0,'TimeZone','UTCLeapSeconds')
t1 =
2012-06-30T00:00:00.000Z
>> t2 = datetime(2012,7,2,0,0,0,'TimeZone','UTCLeapSeconds')
t2 =
2012-07-02T00:00:00.000Z
>> t2 - t1
ans =
48:00:01
That's 48h and 1s. I will make a note to look into the conversion from "unzoned" to 'UTCLeapSeconds', and why you get those extra seconds.
In the third case, you're running 14b, which was released before the 2015 leap second was even announced. There was a patch posted in early January, and the recently-released 15a has the patch already in it. You're right, there needs to be more communication about how to update, although given the current state of affairs, it's not even clear that there will ever be any more leap seconds.
Hope this helps.
Peter Perkins on 6 May 2015
James, I only just saw this, sorry for the long wait. If I understand the question correctly, the problem is that 'UTCLeapSeconds' currently requires a specific display format. You might do one of two things:
1) Call the datetime constructor to do the conversion in one line:
>> t = datetime(2012,7,2,0,0,0,'TimeZone','UTC')
t =
02-Jul-2012 00:00:00
>> tl = datetime(t,'Format','uuuu-MM-dd''T''HH:mm:ss.SSS''Z''','TimeZone','UTCLeapSeconds')
tl =
2012-07-02T00:00:00.000Z
2) Or set the properties one at a time:
>> t = datetime(2012,7,2,0,0,0,'TimeZone','UTC')
t =
02-Jul-2012 00:00:00
>> t.Format = 'uuuu-MM-dd''T''HH:mm:ss.SSS''Z''';
>> t.TimeZone = 'UTCLeapSeconds'
t =
2012-07-02T00:00:00.000Z
Hope this helps. I would think that if you were working in leap seconds, you'd pretty much start off there and stay there. I'd be interested in hearing about why you're converting back and forth. Not saying you're doing anything wrong, just trying to understand.

### More Answers (2)

Steve Allen on 24 Mar 2015
The 24 seconds is not a time of day adjustment. The question is whether the underlying time scale has been counting all of the elapsed SI seconds in the radio broadcasts that correspond to TAI, or whether it has been ignoring some SI seconds so as to stay synchronized with calendar days of mean solar time that are counted by the face value of UTC. If the underlying time scale is counting all of the SI seconds then it must disagree with the POSIX-mandated interpretation of the face value of UTC before and after a leap second. Yes, it is inevitably confusing because there is no international standard for the IANA tz "right" timezones, but on the other hand that "right" interpretation is the only one which actually corresponds with the actual history of the seconds which have been broadcast in the internationally-recommended time signals when counted since all civil clocks had a face value of 1970-01-01T00:00:00.
##### 1 CommentShowHide None
James Tursa on 24 Mar 2015
"... the underlying time scale ..."
That's the point, there is no underlying time scale. It is unzoned (''). The only question is what to do with this when applying a new time zone directly by assignment. To be consistent with the behavior of all other time zones, applying 'UTCLeapSeconds' should not do a time of day adjustment.

Andrew Janke on 31 May 2018
Hi folks. I'm a software developer coming from Java/C#/Joda-Time/Noda-Time, and this behavior is confusing me.
Is there a central documentation page for how the Matlab datetime API handles leap seconds? I couldn't find it anywhere looking through the doco.
##### 1 CommentShowHide None
Peter Perkins on 31 May 2018
Andrew, leaps seconds in MATLAB are "opt in". My experience is that most people don't want their time calculations to consider them at all, and unless you do opt in, MATLAB behaves as if they never happened. You opt in by setting the TimeZone property to 'UTCLeapSeconds' (This isn't really a "time zone" in the same sense that America/New_York is, but that's how it's done). Other than that, there's nothing special.