Formatting Dates and Times

Having recently returned from a vacation in Europe, one of the Scripting Guys was reminded of the following fact: just because Americans do something, that doesn’t mean the rest of the world does that very same thing, or at least not in the very same fashion. This is true when it comes to putting ice in drinks; it’s also true when it comes to formatting dates and times.

For example, in the US we use a 12-hour clock. What does that mean? Well, suppose we’re at lunch, and we glance at the clock; the clock says that it’s 12:59 in the afternoon. Let’s assume that we wait one minute and check the clock again. In much of the world, the clock will read 13:00; that’s because a large portion of the world uses a 24-hour clock. In the US, however, the clock will read 1:00; that’s because a US day is broken into two 12-hour segments: the morning segment (AM) and the evening segment (PM).

The same sort of thing is true when it comes to calendar days. Suppose today is August 31, 2007 (which it is).In the US , we’d list the date like this: 8/31/2007, the format being month/day/year. In a very large portion of the world, however, that same date is listed like this: 31/8/2007, the format being day/month/year. This isn’t to say that one of these approaches is right and the other is wrong. (Even though we Americans always believe that we’re right and everyone elseis wrong; see “the metric system” for more details.) Instead, it’s just to say that any time you work with dates and times there is a chance for confusion. What time is it if it’s 2:15? In Italy, it’s2:15 in the morning; in the US , well, it mightbe 2:15 in the morning, or it might be 2:15 in the afternoon. What date is it if it’s 10/3/2007? Again, in Italy, it’s March 10, 2007; in the US , it’s October 3, 2007. It all depends on where you are and, when it comes to computers, how you’ve configured your Regional and Language Options.

So what does that mean to you, the Windows PowerShell scripter? Well, if you’re working in an international setting, it means that you should always format dates using a specific pattern; that way dates and times will be consistent regardless of a user’s regional and language settings. But what if you’re notworking in an international setting? Well, even then it can be useful to know how to format dates and times. For example, when you call the Get-Datecmdlet Windows PowerShell, by default, displays a value similar to this:

Thursday, August 30, 2007 11:13:51 AM

That’s fine, but what if all you reallywanted was a value like this:

8/30/2007

Hey, no problem. As it turns out, that’s what this week’s Windows PowerShell tip is all about.

Quick Formatting

Thanks to its ability to tap into the .NET Framework, Windows PowerShell offers scores of different ways to format dates and times. For example, you can create fully-customizable date-time formats, something we’ll address in a moment. Alternatively, you can use one of these standard date-time formats:

 Specifier Format Sample Output d ShortDatePattern 8/30/2007 D LongDatePattern Thursday, August 30, 2007 f Full date and time (long date and short time) Thursday, August 30, 20 F FullDateTimePattern(long date and long time) Thursday, August 30, 2007 11:19:59 AM g General (short date and short time) 8/30/2007 11:20 AM G General (short date and long time) 8/30/2007 11:20:24 AM m, M MonthDayPattern August 30 o Round-trip date/time pattern 2007-08-30T11:18:49.0312500-07:00 r, R RFC1123Pattern Thu, 30 Aug 2007 11:21:36 GMT s SortableDateTimePattern(based on ISO 8601) using local time 2007-08-30T11:20:36 t ShortTimePattern 11:20 AM T LongTimePattern 11:20:42 AM u UniversalSortableDateTimePatternusing the format for universal time display 2007-08-30 11:21:50Z U Full date and time (long date and long time) using universal time Thursday, August 30, 2007 6:21:52 PM y, Y YearMonthPattern August, 2007

That’s all well and good, but how do you applythese date-time formats? As it turns out, that’s easy: all you need to do is tack on the –formatparameter followed by the appropriate specifier. For example, suppose you want to apply the ShortDatePatternformat. No problem:

Get-Date –format d

To apply the LongDatePatternuse the D specifier:

Get -Date –format D

Etc., etc.

If you want to, you can also assign this formatted date-time value to a variable, like so:

\$a = Get-Date –format M

Do that and display the value of \$a; you should get back something that looks like this:

August 30

And that’s all you’re going to get back (the month and the day), no matter where you live and no matter how you’ve configured your regional and language settings.

Custom Formatting

Maybe these built-in date-time formats work for you and maybe they don’t. Let’s assume that they don’t, that you need a customized date-time format. What then?

Well, you know what they say: they say … well, come to think of it, we don’t have any idea what they say. But what they shouldsay is this: if you want a customized date-time format, then you should use the .NET Framework to build a customized date-time format yourself. That’s something you can do using custom date-time specifiers, some of which (the more commonly-used ones) are shown in the following table:

Note. You can find a complete list of specifiersin the .NET Framework SDK on MSDN.

We aren’t going to bother running through all the possible combinations and permutations here; needless to say, that would take awhile. However, we will show you a couple of examples, the better to get you started in the wonderful world of custom date-time formatting. For example, suppose you’d like a date-time value that looked like this, with the month followed by a period followed by the day (and another period) followed by the year:

8.30.2007

How can we do that? Like this:

Get-Date -format M.d.yyyy

Nothing too fancy here: we simply use the –format parameter followed by the desired format (including the periods). What if we wanted to show the year, the abbreviated name of the month, and then the day, all separated by blank spaces?

2007 Aug 30

We can do that:

Get-Date -format " yyyyMMM d"

Again, there’s nothing complicated about this: we simply add the –format parameter followed by the appropriate specifiers. The one thing to watch out for?Because our formatting string includes blank spaces, we need to enclose the entire string in double quote marks. That’s about as complicated as it gets.

I Format, uFormat, We All Format

You say that’s not enough? You say you want even morecustom formatting options? Well, as it turns out, the Get-Date cmdlet includes another parameter ( - uformat) which enables you to display date and time information in Unixformat. We won’t discuss all the available specifiersin today’s article; for more information, see the Windows PowerShell help file . However, we will mention two interesting (and useful) specifiers: %jand %V. (And yes, you do need to include the percent signs when referencing these specifiers.) The %j specifierreturns the day of the year; for example:

Get-Date - uformat%j
242

The %V specifierreturns the week of the year:

Get-Date - uformat%V
35

And, as always, the Get-Date cmdlet can be used with anydate, not just the current date. Want to know the day of the year for March 13, 2008? Okey-doke:

Get-Date 3/13/2008 - uformat%j
73

Pretty cool, huh? See you next week.