dotnet / dotnet/dotnet-api-docs

Leap second statement is confusing

Open
#966 12 comments 0 reactions 0 assignees View on GitHub
area-System.DateTime doc-enhancement dotnet-api/prod Pri2
Dominant language
C#
Stars
949
Forks
1.7k
Avg merge
3d 27m
Merged PRs (30d)
49

Description

At the time of writing, the documentation reads

> represents the number of seconds that have elapsed

and

> does not take leap seconds into account

I found this wording confusing. At first reading, I questioned whether the calculation treated leap seconds differently from absolute monotonic seconds, as it should. Based on cursory tests, I can see that calculations are correctly performed in the calendar domain (UTC), not the time domain (TAI). The best wording I have seen to date is this, by [Markus Kuhn](https://www.cl.cam.ac.uk/~mgk25/posix-clocks.html):

> The POSIX second count ignores inserted leap seconds (and does not even provide an encoding for them) and counts deleted leap seconds

In practice, unix time represents a UTC date and time as a set of fields packed into an integer value according to a formula set by POSIX. The companion definition of unix time as a measure of elapsed time cannot be reconciled with this formula; it is effectively a false correspondence rooted in history and is a common source of error. It appears that ToUnixTimeSeconds [uses the latter definition](https://referencesource.microsoft.com/#mscorlib/system/datetimeoffset.cs) and conforms because the DateTimeOffset.Ticks shares the same limitation regarding leap seconds. The documentation there is more clear:

> It does not include ticks that would be added by leap seconds.

(edited to fix blockquote)
---
#### Document Details

⚠ *Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.*

* ID: 265528c3-9318-aa3c-6c32-a6a2b2b2cedd
* Version Independent ID: 92ea6e5d-653f-ac43-a3bf-9348fc3a0a0f
* Content: [DateTimeOffset.ToUnixTimeSeconds Method (System)](https://docs.microsoft.com/en-us/dotnet/api/system.datetimeoffset.tounixtimeseconds?redirectedfrom=MSDN&view=netframework-4.7.2#System_DateTimeOffset_ToUnixTimeSeconds)
* Content Source: [xml/System/DateTimeOffset.xml](https://github.com/dotnet/dotnet-api-docs/blob/master/xml/System/DateTimeOffset.xml)
* Product: **dotnet-api**
* GitHub Login: @dotnet-bot
* Microsoft Alias: **dotnetcontent**

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.