Update Docs for DateTime.Ticks to explain it depends on the time zone of the object instance.

[AWilco]

Summary

Corrected documentation of Ticks property to include information that it is related to the number of ticks since 0:00:00 on January 1, 0001 in the time zone of the the DateTime instance, and not always UTC. Thus using ToUniversalTime() and ToLocalTime() can change the number of ticks, even though it represents the same instant in time.

As discussed here: https://social.msdn.microsoft.com/Forums/vstudio/en-US/fde7e5b0-e2b9-4d3b-8a63-c2ae75e316d8/datetimeticks-bug?forum=netfxbcl
And tested on .NET 4.5.1.

If this has changed in the latest .NET runtimes, the documentation says that it has not and is the same functionality as 4.5.1

Not known to be an open issue.

[Thraka]

@AWilco Thanks a bunch for correcting this. I'll get someone to double check it. 👍

[AWilco]

@tarekgh I appreciate that what I have written might not be the factual truth of how DateTime works.

What I intended to convey was that the Ticks property is NOT always the number of ticks since 0:00:00 UTC on January 1, 0001. As I understand it, given limited testing myself and reviewing the discussion thread I linked to, if a timezone is set then the Ticks property is the number of ticks since 0:00:00 on January 1, 0001 in that timezone.

Practically what I was attempting to solve was that when I read that description, I then assume that if I take a specific instant in time represented in a DateTime Object, e.g. 2019-10-01T00:00:00UTC
and change the timezone used to represent that instant, e.g. to
2019-10-01T01:00:00UTC+1

Then the Ticks property would stay the same, as the elapsed time between either of those dates and 0:00:00 UTC on January 1, 0001. However this is not true.

As a test:

            var dateInUtc = new DateTime(1, 1, 1, 1, 0, 0, DateTimeKind.Utc);
            var ticksInUtc = dateInUtc.Ticks;
            var dateInLocal = dateInUtc.ToLocalTime(); //My local time zone is London time, as of writing it is UTC+1
            var ticksInLocal = dateInLocal.Ticks;
            Assert(ticksInUtc - ticksInLocal == 0); //This fails

My new description may not be 100% accurate, I don't know enough about DateTime to ensure what I write is fully accurate, I would appreciate help in improving my new text.

Regarding what happens if you use DateTime.Unspecified, converting to UTC or to local appears to avoid adjusting the ticks at all, and just changes the DateTimeKind property. This means that the instant of time that is represented may be different, but the Ticks property will stay the same.

[tarekgh]

@AWilco Thanks for tying to clarify the docs. what about the following? do you think it is good enough or we need to specify more clarification?

The value of this property represents the number of 100-nanosecond intervals that have elapsed since 12:00:00 midnight, January 1, 0001 in the Gregorian calendar, which represents DateTime.MinValue. It does not include the number of ticks that are attributable to leap seconds.
If the DateTime object has Kind property set to Local, that means the ticks inside this object is representing the time elapsed time since 12:00:00 midnight, January 1, 0001 in the local time specified by the current time zone setting.
If the DateTime object has Kind property set to Utc, that means the ticks inside this object is representing the time elapsed time since 12:00:00 midnight, January 1, 0001 in the Coordinated Universal Time.
If the DateTime object has Kind property set to Unspecified, that means the ticks inside this object is representing the time elapsed time since 12:00:00 midnight, January 1, 0001 in some time zone time which not necessary match Local not Utc time.

In general, the ticks represent the time according to the time zone specified by the Kind property.

[AWilco]

@AWilco Thanks for tying to clarify the docs. what about the following? do you think it is good enough or we need to specify more clarification?

The value of this property represents the number of 100-nanosecond intervals that have elapsed since 12:00:00 midnight, January 1, 0001 in the Gregorian calendar, which represents DateTime.MinValue. It does not include the number of ticks that are attributable to leap seconds.
If the DateTime object has Kind property set to Local, that means the ticks inside this object is representing the time elapsed time since 12:00:00 midnight, January 1, 0001 in the local time specified by the current time zone setting.
If the DateTime object has Kind property set to Utc, that means the ticks inside this object is representing the time elapsed time since 12:00:00 midnight, January 1, 0001 in the Coordinated Universal Time.
If the DateTime object has Kind property set to Unspecified, that means the ticks inside this object is representing the time elapsed time since 12:00:00 midnight, January 1, 0001 **in the same unspecified time zone**

In general, the ticks represent the time according to the time zone specified by the Kind property.

HI Tarek,

Yes, I think what you have is good, although your words about an unspecified time zone seemed to suggest it would be random. In actuality, if the timezone is unspecified, then the whole issue is moot, because there isn't any way to take into account a time zone. The starting instant of 12:00:00 midnight, January 1, 0001 is in the same unspecified time zone. You could aso say that it assumes the time is in UTC for the purposes of this property.

If the DateTime object has Kind property set to Unspecified, that means the ticks inside this object is representing the time elapsed time since 12:00:00 midnight, January 1, 0001 **in the same unspecified time zone**

Either way, what you have proposed is an improvement and doesn't introduce any new inaccuracies.

[Thraka]

@AWilco let me know when you make the changes with the new suggestions. Thanks.

[tarekgh]

@AWilco thanks for the feedback.

You could aso say that it assumes the time is in UTC for the purposes of this property.

We cannot be specific about this assumption here. There are some contexts that unspecified treated as UTC and in other contexts treated as local.
does it make sense if we changed in the same unspecified time zone to in the unknown time zone?

Feel free to suggest something different. My goal is to have anyone reading to understand how to use it. thanks again.

[carlossanlop]

@AWilco do you have an update on the feedback received on this PR?

[AWilco]

@tarekgh @carlossanlop I've updated the change with the new text as discussed.

[carlossanlop]

Left some minor suggestions for you to consider, @AWilco . Thanks for making these changes.

@Thraka, @mairaw, @gewarren it would be awesome if you could double check my language review.

[gewarren]

I made a couple small tweaks to Carlos' suggestions.

[AWilco]

Thanks, I believe I have accepted all the proposed changes.

Changes were completed

[Thraka]

@AWilco Awesome! Thanks a bunch for the updates.