PowerShell's -f formatting operator uses the .NET Framework's string formatting "engine" to manipulate text, numeric, date and time data.  In its simplest form it behaves like the C, C++ and PHP sprintf function, that is, it allows data to be inserted into a string at given positions with optional width and alignment specifications.  However, the -f operator goes much further, providing numerous format specifications, which will be described below.

The most basic use of the -f operator is simple positional data insertion.  In this form, place holders are inserted into the format string in the desired position(s).  The place holders take the following form:


...with the <INDEX> value specifying which of the supplied data items to insert, for example:

PS C:\Users\JohnDoe> 'The {0} sat on the {1}.' -f 'cat', 'mat'; The cat sat on the mat. PS C:\Users\JohnDoe>

Data items can be referenced multiple times, and in any order, for example:

PS C:\Users\JohnDoe> "{1} had a little {0}.`r`nIt's fleece was white as snow,`r`nAnd everywhere that {1} went,`r`nThe {0} was sure to go." -f 'lamb', 'Mary'; Mary had a little lamb. It's fleece was white as snow, And everywhere that Mary went, The lamb was sure to go. PS C:\Users\JohnDoe>

Using the -f operator in this way makes string construction code far more readable and maintainable, as the structure of the data and the data itself are kept separate.  This becomes particularly useful when building long strings with numerous items of data interspersed throughout (for example, dynamically generated SQL queries).   Each item of data inserted into a string can be assigned a width and a left or right alignment directive.  The place holders now take the form:



For example:

PS C:\Users\JohnDoe> '>{0,-20}<' -f 'Left aligned.'; # Left-align; no overflow. >Left aligned. < PS C:\Users\JohnDoe> '>{0,20}<' -f 'Right aligned.'; # Right-align; no overflow. > Right aligned.< PS C:\Users\JohnDoe> '>{0,-20}<' -f 'Left aligned, but too wide.'; # Left-align; data overflows width. >Left aligned, but too wide.< PS C:\Users\JohnDoe>

So, that's the basics out of the way.  To recap, we've seen that we can insert various data items into a given string and control the width and alignment of each data item.  The next step is to transform the input data using various format specifications.  For a final time, the place holders now take the following form:


The remainder of this section will describe each of the available <FORMAT_SPEC> options.

The following format specifications deal with date and time data in the form of .NET's System.DateTime data type.

PowerShell's custom date and time format specifications give full control over date and time formatting.  Some of the specifications overlap those of the standard date and time format strings, described above.  However, they only take effect if the format string is clearly a custom string, for example, {0:d} will always be parsed as a short date format, whereas {0:d d} would return two instances of the current day of the month.