Kathy Kam : BCL types

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".

.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>

.NET Format String 101

KathyKam — Thu, 30 Mar 2006 02:31:00 GMT

"I see stuff like {0,-8:G2} passed in as a format string. What exactly does that do?" -- Very Confused String Formatter

The above format can be translated into this:

"{<argument index>[,<alignment>][:<formatString><zeros>]}"

argument index: This represent which argument goes into the string.

String.Format("first = {0};second = {1}", "apple", "orange");

String.Format("first = {1};second = {0}", "apple", "orange");

gives the following strings:

"first = apple;second = orange"

"first = orange;second = apple"

alignment (optional): This represent the minimal length of the string.

Postive values, the string argument will be right justified and if the string is not long enough, the string will be padded with spaces on the left.

Negative values, the string argument will be left justied and if the string is not long enough, the string will be padded with spaces on the right.

If this value was not specified, we will default to the length of the string argument.

String.Format("{0,-10}", "apple"); //"apple "

String.Format("{0,10}", "apple"); //" apple"

format string (optional): This represent the format code.

Numeric format specifier is available here. (e.g. C, G...etc.)
Datetime format specifier is available here.

Enumeration format specifier is available here.

Custom Numeric format specifier is available here. (e.g. 0. #...etc.)

Custom formatting is kinda hard to understand. The best way I know how to explain something is via code:

int pos = 10;

int neg = -10;

int bigpos = 123456;

int bigneg = -123456;

int zero = 0;

string strInt = "120ab";

String.Format("{0:00000}", pos); //"00010"

String.Format("{0:00000}", neg); //"-00010"

String.Format("{0:00000}", bigpos); //"123456"

String.Format("{0:00000}", bigneg); //"-123456"

String.Format("{0:00000}", zero); //"00000"

String.Format("{0:00000}", strInt); //"120ab"

String.Format("{0:#####}", pos); //"10"

String.Format("{0:#####}", neg); //"-10"

String.Format("{0:#####}", bigpos); //"123456"

String.Format("{0:#####}", bigneg); //"-123456"

String.Format("{0:#####}", zero); //""

String.Format("{0:#####}", strInt); //"120ab"

While playing around with this, I made an interesting observation:

String.Format("{0:X00000}", pos); //"A"

String.Format("{0:X00000}", neg); //"FFFFFFF6"

String.Format("{0:X#####}", pos); //"X10"

String.Format("{0:X#####}", neg); //"-X10"

The "0" specifier works well with other numeric specifier, but the "#" doesn't. Umm... I think the "Custom Numeric Format String" probably deserve a whole post of it's own. Since this is only the "101" post, I'll move on to the next argument in the format string.

zeros (optional): It actually has a different meaning depending on which numeric specifier you use.

int neg = -10;

int pos = 10;

// C or c (Currency): It represent how many decimal place of zeros to show.

String.Format("{0:C4}", pos); //"$10.0000"

String.Format("{0:C4}", neg); //"($10.0000)"

// D or d (Decimal): It represent leading zeros

String.Format("{0:D4}", pos); //"0010"

String.Format("{0:D4}", neg); //"-0010"

// E or e (Exponential): It represent how many decimal places of zeros to show.

String.Format("{0:E4}", pos); //"1.0000E+001"

String.Format("{0:E4}", neg); //"-1.0000E+001"

// F or f (Fixed-point): It represent how many decimal places of zeros to show.

String.Format("{0:F4}", pos); //"10.0000"

String.Format("{0:F4}", neg); //"-10.0000"

// G or g (General): This does nothing

String.Format("{0:G4}", pos); //"10"

String.Format("{0:G4}", neg); //"-10"

// N or n (Number): It represent how many decimal places of zeros to show.

String.Format("{0:N4}", pos); //"10.0000"

String.Format("{0:N4}", neg); //"-10.0000"

// P or p (Percent): It represent how many decimal places of zeros to show.

String.Format("{0:P4}", pos); //"1,000.0000%"

String.Format("{0:P4}", neg); //"-1,000.0000%"

// R or r (Round-Trip): This is invalid, FormatException is thrown.

String.Format("{0:R4}", pos); //FormatException thrown

String.Format("{0:R4}", neg); //FormatException thrown

// X or x (Hex): It represent leading zeros

String.Format("{0:X4}", pos); //"000A"

String.Format("{0:X4}", neg); //"FFFFFFF6"

// nothing: This is invalid, no exception is thrown.

String.Format("{0:4}", pos)); //"4"

String.Format("{0:4}", neg)); //"-4"

In summary, there are four types of behaviour when using this <zeros> specifier:

Leading Zeros: D, X

Trailing Zeros: C, E, F, N, P

Nothing: G

Invalid: R, <empty>

Now, that we've gone through the valid specifiers, you can actually use this in more than just String.Format(). For example, when using this with Byte.ToString():

Byte b = 10;

b.ToString("D4"); //"0010"

b.ToString("X4"); //"000A"

Wow... this was way longer than I expected. The BCL team is having blog day today, I need to get back to posting something for the BCLWeblog.

One of the lesson I learnt from an earlier post is that, readers are not interested in a post that doesn't give you more information than what MSDN provides. Instead, readers are more interested in seeing stuff that are not available on MSDN. So when I was doing research to post about this topic, I found that MSDN actually talks about exactly what the {0,-8:G2} format does. It is just not easy to find nor centrally located.

For example, in the ToString MSDN Doc, the "Remarks" section covered some basic rules on what a "format string" is. In the String.Format MSDN Doc, the "Remarks" section actually have a pretty detail explaination of what the above format does. Furthermore, MSDN provides a format string overview as well as a the table that specifies all the values that are allowed.

This puts me in an interesting position when writing about this topic. MSDN actually have lots of info that cover it. But since I have also heard more than one person being confused about this topic, I decided to post a summary of the documents and more examples. Do you think this is useful? Should I just stick to posting exclusively on non-MSDN topics?

</Editorial Comment>

Array.Equals

KathyKam — Thu, 09 Mar 2006 04:27:00 GMT

"I wish .NET can compare contents of an Array." - Annoymous Array Comparer

Currently, when you compare two arrays with the = operator, we are really using the System.Object's = operator, which only compares the instances. (i.e. this uses reference equality, so it will only be true if both arrays points to the exact same instance)

Well until we add this feature request in the framework itself, I've provided a temporary solution for you:

public static bool ArrayEquals<T>(T[] a, T[] b)

{

if (a.Length != b.Length)

return false;

for (int i = 0; i < a.Length; i++)

{

if (!a[i].Equals(b[i]))

return false;

}

return true;

}

Again, my solution is not perfect, because if you are comparing value types, I am boxing the value type before calling System.Object::Equal as you can see here:

IL_0026: box !!T
IL_002b: constrained. !!T
IL_0031: callvirt instance bool [mscorlib]System.Object::Equals(object)

My office neighbour Brian Grunkemeyer have the following perf suggestions:

1) Add a generic constraint to this method

public static bool ArrayEquals<T>(T[] a, T[] b) where T: IEquatable<T>

This will help our performance, but limits the method to only take types that implement IEquatable<T>. This may be too restrictive for some though.

2) Use EqualityComparer<T>.Default's Equal method instead of calling Equals on the types themselves.

public static bool ArrayEquals<T>(T[] a, T[] b)

{

if (a.Length != b.Length)

return false;

EqualityComparer<T> comparer = EqualityComparer<T>.Default;

for (int i = 0; i < a.Length; i++)

{

if (!comparer.Equals(a[i], b[i]))

return false;

}

return true;

}

Without measuring the perf of these on long arrays, my guess is that for value types #1 has the best perf, followed by #2 and then the original implementation.

What do you think?

Rounding Up

KathyKam — Wed, 08 Mar 2006 04:40:00 GMT

Since my last post, some people asked me "Well.. great... how do I round up?" Particularly since SQL doesn't do the same rounding as the CLR. SQL's default (and only) rounding algorithm is Rounding Up.

i.e.
SELECT ROUND(2.45, 2), ROUND(2.45, 1)
GO
SELECT ROUND(3.45, 2), ROUND(3.45, 1)
GO
SELECT ROUND(-2.45, 2), ROUND(-2.45, 1)
GO
SELECT ROUND(-3.45, 2), ROUND(-3.45, 1)
GO

Returns:
------- -------
2.45 2.50
3.45 3.50
-2.45 -2.4
-3.45 -3.4

In order to achieve the same rounding as SQL from .NET, you can simply write something like this:

    public static double MathRoundUp(double d, int decimals) 
    { 
        if (d < 0) 
        { 
            double pow = Math.Pow(10, (decimals + 2) * -1); 
            d += pow; 
        } 
        d = Math.Round(d, decimals, MidpointRounding.AwayFromZero); 
        return d; 
    }

If you have a better algorithm, send it to me!

Math.Round - MidpointRounding Enum

KathyKam — Wed, 22 Feb 2006 21:09:00 GMT

I have received some requests to talk about how you can control rounding in Whidbey. So here we go.... :) In Everett, the CLR only support one type of rounding. The Math.Round uses Banker's Rounding Algorithm . (This is the algorithm banks use.. thus...(read more)