Kathy Kam : DateTime and TimeZone2

CurrentCulture, CurrentUICulture and DateTime strings

KathyKam — Wed, 12 Mar 2008 02:23:11 GMT

There are a lot of blogs out that that tries to explain which is what, and why it is the way it is.

To those of you who just want to know what the results are. I wrote a quick little app to show what happens.

As you can see, DateTime.ToString() formatting is driven purely by CurrentCulture.

You can read more about the reasons and background here:

For other DateTime Format String info, check out my blog post ".NET Format String 102: DateTime Format String".

Bye bye "System.TimeZone2", Hello "System.TimeZoneInfo"

KathyKam — Thu, 29 Mar 2007 08:34:00 GMT

Did I catch your attention? I know I haven't posted anything interesting in a while. I am currently working on a project that is unannouced.

However, I want to let everyone know that in Orcas Beta1, that will be release in a few months, the BCL team decided to rename this new type to "System.TimeZoneInfo". This should come as no surprise to my regular readers. We got a lot of feedback on Krzsyztof's blog, the BCL blog, my blog and the BCL Feedback about the name.

Though personally, I find that System.TimeZone2 clearly indicates to a new .NET users that System.TimeZone is basically obsolete. I do agree with everyone's feedback that using numeric modifier is not scalable in the long term. It is a tough call, but given the incredible amount of feedback we got. It looks like System.TimeZoneInfo would be a better name. My only hope is that I don't get another flood of feedback from people who loved the System.TimeZone2 name and System.TimeZoneInfo.

We do value your feedback. So, what do you think?

Orcas October CTP available - Hello, "System.DateTimeOffset"!

KathyKam — Tue, 31 Oct 2006 00:56:00 GMT

Once again, I am very excited that the new CTP is available. :) My second feature for Orcas is available to the world! The BCL team has gotten plenty of feedback (as you can see the comments from my BCL post and on this blog...) about needing an object to represent exact point in time! (We do listen!!)

Oh and for those of you who has been reading my blog regularly... this is the third most debated name on the BCL: "DateTimeOffset". I will explain why later this month in my "Desiging DateTimeOffset" posts. Again, a starter guide will be posted on the BCL blog very soon. This time, I think our new PM Justin will be doing it instead of me. I still need to write a "Advance feature for TimeZone2".

A new date time data structure that can specify an exact point in time relative to the UTC time zone.

The current DateTime is insufficient at specifying an exact point in time. DateTimeOffset represents a date time with an offset. It is not meant to be a replacement for DateTime; it should be used in scenarios involving absolute points in time. DateTimeOffset includes most of the functionality of the current DateTime API and allows seamless conversion to DateTime as well.

Again, for my loyal readers here... a little sneak preview

void CreatingADateTimeOffset()

{

DateTime currentDateTime = GetUserDateTime();

TimeSpan userOffset = GetUserOffset();

DateTimeOffset pointInTime = new DateTimeOffset(currentDateTime , userOffset);

}

Designing System.TimeZone2 - Part 2 (Dynamic Time Zone support)

KathyKam — Fri, 06 Oct 2006 03:59:00 GMT

There are some great discussion on the differences between System.TimeZone and System.TimeZone2 and what exactly is Vista Dynamic Time Zone in my previous post. So I thought I'll spend Part 2 talking about it.

So what exactly is the difference? I have mentioned again and again that the difference is in "Vista Dynamic Time Zone support". But another major difference is that, in System.TimeZone the only time zone you can use was current time zone. That's it. TimeZone2 is way more flexible than that. Users can create their own time zone using the CreateTimeZone API or use the OS provided time zone. (I really need to blog about the CreateTimeZone API... that's on my to-do list)

"So what exactly is this "Vista Dynamic Time Zone support"?"

The word "dynamic" itself is a little misleading. It is not "dynamic". It is more "historic" or "futuristic". "Dynamic time zone data" is just the new registry structure that Vista has introduced so that an application can query a time zone's historic (and future) data. It is dynamic in the sense that as you move forward it time, the OS will update your current time zone information based on the data.

"So does TimeZone2 do different things on different OS?"

Short Answer: No it does not.

Long Explaination:

Let's take a look at "IsDaylightSavingTime".

For System.TimeZone2:
public bool IsDaylightSavingTime (
DateTime time
)

On Vista, if you call FindSystemTimeZoneById, TimeZone2 will be populated with historic and future time zone data (aka dynamic time zone data). On Win XP, if the OS has not been updated with this new data (we are hoping that Windows will backport dynamic time zone data to XP btw...), TimeZone2 will be populated with the current time zone data the OS provides. TimeZone2 doesn't have different logic. The difference here is the data that was provided by the OS. The difference is in FindSystemTimeZoneById(). The call "IsDaylightSavingTime()" does the same thing in both OS.

Two TimeZone2 object with the same data will return the same thing across all the instance methods. You can populate a TimeZone2 object with historical data in WinXP and it will work like it does in Vista. Similarly you can also populate a TimeZone2 object without historical data in Vista and it will work like it does in XP. It all works the same.

The only difference the different OS brings is in the static methods that queries data from the OS. If the OS have different data, the static methods will return different results. This is no different to if you call "GetOSHelloString()" and one OS returns strHello = "Hello World", and another reutrns strHello = "Hello". Would you consider strHello.Length returnng different results and "doing different things on different OS"?

The APIs that calls the OS to get the data all have the word "SystemTimeZone" in it.

- GetSystemTimeZone()
- FindSystemTimeZoneById(string id)
- ConvertBySystemTimeZoneId(string id)

So the "SystemTimeZone" APIs are really helpers for you to get to the OS time zone data. TimeZone2 can operate on other data. (Again, I really need to post a blog about the CreateTimeZone APIs... )

For developers who wants to use OS data but is worried about different OS having different data, we do recomend them serializing the TimeZone data when doing cross application communication.

Now let's look at System.TimeZone, for the same API. It behaves completely differently.
public static bool IsDaylightSavingTime (
DateTime time,
DaylightTime daylightTimes
)

First of all, it is a static method. Secondly, it takes a DaylightTime to calculate whether it is in daylight saving time. It has no understanding of the OS time zone data.

This is why just augmenting or changing System.TimeZone will be a huge breaking change for our exisiting customers. Basically, we'll gut System.TimeZone and replace it with what we call "System.TimeZone2". When we realize that's what we'll do. We decided that we are basically creating a new type. Thus, the birth of System.TimeZone2.

Does this make sense? Do you agree? Disagree?

Designing System.TimeZone2 - Part 1 (API naming and new class or not)

KathyKam — Wed, 04 Oct 2006 07:20:00 GMT

Didn't I say it two weeks ago that API naming is the most difficult thing? :) My BCL post on System.TimeZone2 has been out for about 12 hours, and the top complaint has been .... can you guess it... yes... the name!

You might even think that I knew this was going to attract some controversy and so I prep you guys with that post. But no, naming the new class System.TimeZone2 was not a controversal witin Microsoft at all. It doesn't even make it into the top 10 debated names. ;) Once we have reached the decision that we do need a new class for the extended time zone functionality and that this new class was going to totally replace System.TimeZone. There was no question in any of our reviewers' or approvers' mind what this class should be called. Actually, we all agree that calling it by any other name will actually make it more ambiguous what our intentions is.

Users of the .NET framework will know, System.TimeZone2 is to replace System.TimeZone. There is no functionatlity that can be performed in System.TimeZone that cannot be done with System.TimeZone2. We did see people cringe at first, but that's more of a gut reaction to.. why can't we extend System.TimeZone rather than the naming issue. Now why is extending Time Zone support a whole different class is much worthier debate in my mind.

I know some people have been wondering whether this decision was made because of this Orcas "Red" bits vs Orcas "Green" bits limitation. No need to call the MythBusters... I can bust this myth right here and now. This is not the reason. Every feature in Orcas goes through an Architect review to make sure we don't add a new class just because of this "Red" bits "Green" bits rule. (Trust me.. we don't like adding new classes, and we are VERY concern about framework pollution.) If extending System.TimeZone was what we're going to do anyways, then we'll do it in "Red" bits or wait a release. However, after weighing in the pros and cons, it was obvious to us that we'll never just modify System.TimeZone.

It is obvious in the beginning that if we were to extend time zone support in the framework, we have to support Vista's Dynamic Time Zone APIs. Otherwise, we are just bandaiding the problem and waiting for another TimeZone++ to happen. Leveraging Vista's dynamic time zone support is equivalent to overhauling and dumping the old time zone functionality. The whole idea of "daylightsaving" time is different. We're now looking at historic data as well as current data.

Next, we took a look of most requested features from our customers (yes... we do listen.. send us more feedback!) and took a look at what System.TimeZone already has. It was decided that if we were to add a new class, there is no reason to add support to Vista's dynamic time zone and these new features without also having all System.TimeZone's functionality (but implemented differently). (Side Note: We did thought about having a class that doesn't replace System.TimeZone, but merely augments it for the extra support. But it wasn't hard to realize that wouldn't be good.) So, how much breaking changes would require System.TimeZone to have if we were to add all these new features? The answer is .... a lot. I asked last time.. how much breaking will our users tolerate? So, after weighing in everything, we decided that we need a new class, and this new class that needs to do everything that System.TimeZone does. So it only make sense to deprecate System.TimeZone, and introduce this new class as its replacement.

Now, regarding everyone's feeling about the guideline:

"Do use a numeric suffix to indicate a new version of an existing API if the existing name of the API is the only name that makes sense"

I actually pinged Brad and Krzsyztof about your feedback. Hopefully one of them will post something about this soon. :)

I hope this explains some of our reasoning. What do you think? Agree? Disagree?

System.TimeZone2 Starter Guide is now posted!

KathyKam — Tue, 03 Oct 2006 20:45:00 GMT

I have posted my starter guide on the BCL team blog! I'll post a follow up and advance usage guide here in this blog. Check back for it :)

http://blogs.msdn.com/bclteam/archive/2006/10/03/System.TimeZone2-Starter-Guide-_5B00_Kathy-Kam_5D00_.aspx

Check it out and let me know what you think of this new class!

.NET Format String 102: DateTime Format String

KathyKam — Fri, 29 Sep 2006 18:00:00 GMT

"I see stuff like "zz" passed into DateTime.ToString(). What exactly does that do?" -- Very Confused DateTime String Formatter

DateTime has its own set format string modifiers because there are so many ways to display a date and time. There are 2 things that affects how your DateTime is formatted.

1. CultureInfo

Besides the format string modifiers, CultureInfo on your thread also greatly influences the output. My examples will be based on CultureInfo.InvariantCulture.

You can set the CultureInfo on your thread by calling this

Thread.CurrentThread.CurrentCulture = <some culture>;
eg.
Thread.CurrentThread.CurrentCulture = CultureInfo.InvariantCulture;
Thread.CurrentThread.CurrentCulture = new CultureInfo("en-US");
Thread.CurrentThread.CurrentCulture = new CultureInfo("de-DE");

2. Format String

There are actually two different ways of formatting a DateTime object. Both methods produce the same results:

DateTime now = DateTime.Now;

now.ToString("<dateTimeFormatString>");

String.Format("<strFormat>", now);

Basically:

<strFormat> = {<argument index>:<dateTimeFormatString>}

My examples will use the DateTime.ToString() method.

If you have read any DateTime format string documentation, you will know that the .NET platform has two different styles of DateTime format string:

2-a. Standard Format String

This is basically built in short hand for custom format string. You pass in the one character string to denote which custom format you want.

i.e.
now.ToString("d"); // "09/27/2006"
now.ToString("D"); // "Tuesday, 27 September 2006"
now.ToString("G"); // "09/27/2006 14:15:39"

All of the format string syntax I discussed in ".NET Format String 101" is invalid here. Also, if you call now.ToString(), it is basically calling now.ToString("G");

I have included my own table mapping Standard Format String to Custom Format string in part 2-c below. MSDN actually has a pretty good table that describe what each item does, and DateTime.ToString() has a pretty good code example that shows what each format string specifier do. Also if you just want samples, MSDN has a "Standard Date Time Format String Output example" here. Because documentation is so good. I won't go into this too much. :)

2-b. Custom Format String

Custom format string gives you the flexibility to build your own formatting. When using a single character format string specifier, you will need to prepend it with a "%", otherwise it will be interpreted as a Standard Format String. Here are the basics for building your own string:

DateTime now = new DateTime(2006, 9, 07, 15, 06, 01, 08, DateTimeKind.Local);

now.ToString(); //"09/27/2006 15:06:01"

Year

now.ToString("%y"); //"6"

now.ToString("yy"); //"06"

now.ToString("yyy"); //"2006"

now.ToString("yyyy"); //"2006"

Month

now.ToString("%M"); //"9"

now.ToString("MM"); //"09"

now.ToString("MMM"); //"Sep"

now.ToString("MMMM"); //"September"

Day

now.ToString("%d"); //"7"

now.ToString("dd"); //"07"

now.ToString("ddd"); //"Thu"

now.ToString("dddd"); //"Thursday"

Hour

now.ToString("%h"); //"3"

now.ToString("hh"); //"03"

now.ToString("hhh"); //"03"

now.ToString("hhhh"); //"03"

now.ToString("%H"); //"15"

now.ToString("HH"); //"15"

now.ToString("HHH"); //"15"

now.ToString("HHHH"); //"15"

Minutes

now.ToString("%m"); //"3"

now.ToString("mm"); //"03"

now.ToString("mmm"); //"03"

now.ToString("mmmm"); //"03"

Seconds

now.ToString("%s"); //"1"

now.ToString("ss"); //"01"

now.ToString("sss"); //"01"

now.ToString("ssss"); //"01"

Milliseconds

now.ToString("%f"); //"0"

now.ToString("ff"); //"00"

now.ToString("fff"); //"008"

now.ToString("ffff"); //"0080"

now.ToString("%F"); //""

now.ToString("FF"); //""

now.ToString("FFF"); //"008"

now.ToString("FFFF"); //"008"

Kind

now.ToString("%K"); //"-07:00"

now.ToString("KK"); //"-07:00-07:00"

now.ToString("KKK"); //"-07:00-07:00-07:00"

now.ToString("KKKK"); //"-07:00-07:00-07:00-07:00"

// Note: The multiple K were just read as multiple instances of the

// single K

DateTime unspecified = new DateTime(now.Ticks, DateTimeKind.Unspecified);

unspecified.ToString("%K"); //""

DateTime utc = new DateTime(now.Ticks, DateTimeKind.Utc);

utc.ToString("%K"); //"Z"

TimeZone

now.ToString("%z"); //"-7"

now.ToString("zz"); //"-07"

now.ToString("zzz"); //"-07:00"

now.ToString("zzzz"); //"-07:00"

Other

now.ToString("%g"); //"A.D."

now.ToString("gg"); //"A.D."

now.ToString("ggg"); //"A.D."

now.ToString("gggg"); //"A.D."

now.ToString("%t"); //"P"

now.ToString("tt"); //"PM"

now.ToString("ttt"); //"PM"

now.ToString("tttt"); //"PM"

2-c. Additional Resources

Now that you understand what Standard and Custom format strings are, here is a table of Standard Format String to Custom Format String mapping:

Year Month Day Patterns:
d = "MM/dd/yyyy"
D = "dddd, dd MMMM yyyy"
M or m = "MMMM dd"
Y or y = "yyyy MMMM"

Time Patterns:
t = "HH:mm"
T = "HH:mm:ss"

Year Month Day and Time without Time Zones:
f      = "dddd, dd MMMM yyyy HH:mm"
F      = "dddd, dd MMMM yyyy HH:mm:ss"
g      = "MM/dd/yyyy HH:mm"
G      = "MM/dd/yyyy HH:mm:ss"

Year Month Day and Time with Time Zones:
o      = "yyyy'-'MM'-'dd'T'HH':'mm':'ss.fffffffK"
R or r = "ddd, dd MMM yyyy HH':'mm':'ss 'GMT'"
s      = "yyyy'-'MM'-'dd'T'HH':'mm':'ss"
u      = "yyyy'-'MM'-'dd HH':'mm':'ss'Z'"
U      = "dddd, dd MMMM yyyy HH:mm:ss"

All other single characters will throw an exception.

Answering the question...

So finally, to answer the question that began this whole discussion. "What exactly would "zz" do?" i.e. What would "now.ToString("zz")" return?

Because there are 2 characters, it will be interpreted as a custom format string. "zz" stands for the signed time zone offset with a leading zero for single digit offsets. For me, being in Pacific Standard Time, my return value would be "-07".

<Editorial Comment>
My most popular post was ".NET Format String 101". The topic I have posted the most about is DateTime, Time Zone and so forth. It only seem fitting that I write a post about Format Strings in DateTime. I hope readers enjoy this post as much as my previous Format String post. :) I know MSDN actually covers this better than normal Format String, so I am not sure whether this is as valuable. What do you think? Are there any more "hot topics" that you are just dying for someone to explain?

Also, here are the MSDN resources:
- DateTime.ToString
- Standard DateTime Format Strings
- Standard Date Time Format String Output
- Custom DateTime Format Strings
- Custom DateTime Format Strings Output Examples

</Editorial Comment>

Orcas September CTP available... Hello "System.TimeZone2"!

KathyKam — Fri, 29 Sep 2006 04:30:00 GMT

I am so excited that the CTP is finally available! As soon as you crack open the bits, you'll find what I have been working months on! Can you guess what it is???

NET Framework improvements such as:

New managed add-in model enables developers to add a version-resilient extensibility model to their products.
Support for time zone conversion, enumeration and serialization, including cases where Daylight Saving Time rules change over time.
Reflection in Partial Trust, enabling sand box scenarios for all applications that depend on these features.
The ability to control the garbage collector’s latency mode
Improved CLR ThreadPool micro-performance and throughput for worker and IO completion

The class that have those functionality is System.TimeZone2. I will be posting some samples and quick guide on the BCL team blog probably next Tuesday. For my loyal readers here... I'll treat you wit the most basic sample on how to convert a DateTime with this new class right now!!! This example converts a DateTime from my home town "Sydney, Australia" to "Redmond, WA, USA".

void BasicConvertScenarios()

{

DateTime newTime;

DateTime currentDateTime = GetUserDateTime();

string ausTimeZoneId = "AUS Eastern Standard Time";

string pstSystemId = "Pacific Standard Time";

newTime = TimeZone2.ConvertTimeBySystemTimeZoneId(userDateTime,

ausTimeZoneId,

pstSystemId);

}

I am so excited! Let me know what you think! People have been asking for this so much... I hope their needs are met!

The CTP is available here: http://www.microsoft.com/downloads/details.aspx?FamilyID=82243606-d16d-445c-8949-9ee8c10cda2e&DisplayLang=en

Is modifying System.DateTime reasonable for a Time Zone/Offset aware DateTime object?

KathyKam — Tue, 05 Sep 2006 10:35:00 GMT

So, in my previous "Designing Time Zone Conversion" post, a few readers asked whether we can update System.DateTime to understand Time Zones.

Before we look into whether we can update DateTime, we should look into how this "improved" DateTime should function. Users want a class that can specified a specific point in time. Some users had asked for a DateTime that acutally understands Time Zone. i.e. it is permanently associated with a Time Zone and applies the Time Zone rules as it changes, other users wants a DateTime that has an offset to UTC (i.e. not mapped to a Time Zone). Both feature requests are really asking for the same thing. A DateTime class that describe a particular point in time. Currently, DateTime can describe a particular point in time.. that is if you are describing it in UTC or in your local time zone. However, UTC is hard for people to work with; people do not think of their time in UTC. Only working in your local time zone is difficult too. Technology has basically shrunk the globe. People are attending meeting all over the world, or doing it over technologies like Live Meeting. Now, to design this new class let's look at the basic requirements:

- able to describe a single point in time unambiguously
- display the time in UTC, Local or other Time Zone or Offset.
- support functionality available in DateTime

Now, what about other scenarios that DateTime used to support? For example, describe a "date" with no time association or describe a "time" with no date associations. What if you don't know the time zone or offset? You just want to say "I have this Date and Time", sometimes you'll be working with a legacy application and they produce date time with no time zone associated with it. You need to be able to specify an "unspecified" Time Zone/Offset then. Now, how should this new DateTime object work between the two modes ("have a specific point in time" vs "not having it"?) How do you convert between the two modes? Would having 2 modes in one type be a good thing or would that just confuse users. If we have two modes, shouldn't we just have two objects? Since the two objects cannot easily interrop between each other?

These are just some consideration we have to consider before deciding whether we should make a breaking change and modify System.DateTime. Yes.... measuring how much we'll have to break is another consideration. Making DateTime be TimeZone/Offset aware will be a breaking change. What does DateTime.Kind means then? How should it act? How should the Add/Subtract functionality behave, what about Parse and ToString....etc. We need to ask these questions to each and every API DateTime support.

What do you think? Do you think it even make sense to update DateTime? How much "breaking" will you tolerate so that we modify DateTime to have this support?

Answer of the month: IsDaylightSavingTime() or not?

KathyKam — Fri, 11 Aug 2006 18:00:00 GMT

Answer:

static DateTime GetAnswer()

{

DateTime utc = new DateTime(2006, 10, 29, 8, 30,

0, DateTimeKind.Utc);

return utc.ToLocalTime();

}

Explaination:

The main "trick" in this question is that the DateTime I want actually lands in the ambiguous hour when you fall back in Pacific time zone (PST). On first glance, most of you would probably created a DateTime like so:

static DateTime GetAnswer()

{

DateTime wrong = new DateTime(2006, 10, 29, 1, 30, 0);

return wrong;

}

However, when asking the Date Time whether it is in DaylightSavingTime or not, it will default to False. Because, by default, if a DateTime is ambiguous it will default to being the later repeated hour. i.e. the one not in Daylight Saving Time.

So, how can we get it? As you can see in the answer, the key to it is using UTC. UTC does not have daylight saving, it always map to exact point in time. The System.DateTime class has built in support to map Local time back to whatever UTC time you converted it from. That's why you can create a local ambiguous time that can tel whether you are in the first hour (in daylight saving) or the second hour (in standard time).

Did you guys already know this? If so, do you find this useful?

Quiz of the Month: IsDaylightSavingTime() or not?

KathyKam — Sat, 29 Jul 2006 03:04:00 GMT

Question: Given your machine is in Pacific Time (PST) Time Zone, what is MainProgram.GetAnswer so that MainProgram.Test returns true?

class MainProgram

{

static DateTime GetAnswer()

{

????

}

static bool Test()

{

DateTime a = MainProgram.GetAnswer();

String actual = String.Format("DateTime: {0}; IsDaylightSavingTime: {1}", a, a.IsDaylightSavingTime());

String expected = "DateTime: 10/29/2006 1:30:00 AM; IsDaylightSavingTime: True";

return (actual == expected);

}

static void Main(string[] args)

{

}

P.S. The answer will post in a week! I promised this time!

Note: Updated a clause here, that your machine needs to be in Pacific Time Zone