Skip to main content

.NET Format String 102: DateTime Format String

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

Comments

Popular posts from this blog

Tip/Trick: Fix Common SEO Problems Using the URL Rewrite Extension

Search engine optimization (SEO) is important for any publically facing web-site.  A large % of traffic to sites now comes directly from search engines, and improving your site’s search relevancy will lead to more users visiting your site from search engine queries.  This can directly or indirectly increase the money you make through your site. This blog post covers how you can use the free Microsoft  URL Rewrite Extension  to fix a bunch of common SEO problems that your site might have.  It takes less than 15 minutes (and no code changes) to apply 4 simple  URL Rewrite  rules to your site, and in doing so cause search engines to drive more visitors and traffic to your site.  The techniques below work equally well with both ASP.NET Web Forms and ASP.NET MVC based sites.  They also works with all versions of ASP.NET (and even work with non-ASP.NET content). [In addition to blogging, I am also now using Twitter for quick updates and to sh...

ASP.NET MVC - Set custom IIdentity or IPrincipal

Here's how I do it. I decided to use IPrincipal instead of IIdentity because it means I don't have to implement both IIdentity and IPrincipal. Create the interface interface ICustomPrincipal : IPrincipal { int UserId { get ; set ; } string FirstName { get ; set ; } string LastName { get ; set ; } } CustomPrincipal public class CustomPrincipal : ICustomPrincipal { public IIdentity Identity { get ; private set ; } public bool IsInRole ( string role ) { return false ; } public CustomPrincipal ( string email ) { this . Identity = new GenericIdentity ( email ); } public int UserId { get ; set ; } public string FirstName { get ; set ; } public string LastName { get ; set ; } } CustomPrincipalSerializeModel - for serializing custom information into userdata field in FormsAuthenticationTicket object. public class CustomPrincipalSerializeMode...

linq orderby multiple columns dynamically

So, it's been a while, but I thought I take moment and do my annual blog post ;). I've been playing around with  ASP.NET MVC  and the Linq stuff for  NHibernate  recently. I was in need of an OrderBy extension method that could take a SQL-Like OrderBy string and sort a IQueryable<> or IEnumerable<> collection. I wrote up an implementation that worked, but I just wasn't satisfied with its internals (quite a bit of reflection to get the correct type to construct a LambdaExpression, etc) At any rate, I couldn't leave well enough alone, and, after a bit of Googling, I ran across this  StackOverflow  answer about Dynamic LINQ OrderBy . The extension method wasn't exactly what I was looking for, but that ApplyOrder method is slick, and solved the portion of my implementation that was bothering me. So, I though I would post up my version in case anybody finds it useful. It handles the following inputs: list.OrderBy( "SomeProperty" ); list.Ord...