PowerShell Pocket Reference, 3rd Edition

Chapter 4. .NET String Formatting

String Formatting Syntax

The format string supported by the format (-f) operator is a string that contains format items. Each format item takes the form of:

{index[,alignment][:formatString]}

index represents the zero-based index of the item in the object array following the format operator.

alignment is optional and represents the alignment of the item. A positive number aligns the item to the right of a field of the specified width. A negative number aligns the item to the left of a field of the specified width:

PS > ("{0,6}" -f 4.99), ("{0,6:##.00}" -f 15.9)
  4.99
 15.90

formatString is optional and formats the item using that type’s specific format string syntax (as laid out in Tables 4-1 and 4-2).

Standard Numeric Format Strings

Table 4-1 lists the standard numeric format strings. All format specifiers may be followed by a number between 0 and 99 to control the precision of the formatting.

Table 4-1. Standard numeric format strings

Format specifier	Name	Description
C or c	Currency	A currency amount: PS > "{0:C}" -f 1.23 $1.23
D or d	Decimal	A decimal amount (for integral types). The precision specifier controls the minimum number of digits in the result: PS > "{0:D4}" -f 2 0002
E or e	Scientific	Scientific (exponential) notation. The precision specifier controls the number of digits past the decimal point: PS > "{0:E3}" -f [Math]::Pi 3.142E+000
F or f	Fixed-point	Fixed-point notation. The precision specifier controls the number of digits past the decimal point: PS > "{0:F3}" -f [Math]::Pi 3.142
G or g	General	The most compact representation (between fixed-point and scientific) of the number. The precision specifier controls the number of significant digits: PS > "{0:G3}" -f [Math]::Pi 3.14 PS > "{0:G3}" -f 1mb 1.05E+06
N or n	Number	The human-readable form of the number, which includes separators between number groups. The precision specifier controls the number of digits past the decimal point: PS > "{0:N4}" -f 1mb 1,048,576.0000
P or p	Percent	The number (generally between 0 and 1) represented as a percentage. The precision specifier controls the number of digits past the decimal point: PS > "{0:P4}" -f 0.67 67.0000 %
R or r	Roundtrip	The Single or Double number formatted with a precision that guarantees the string (when parsed) will result in the original number again: PS > "{0:R}" -f (1mb/2.0) 524288 PS > "{0:R}" -f (1mb/9.0) 116508.44444444444
X or x	Hexadecimal	The number converted to a string of hexadecimal digits. The case of the specifier controls the case of the resulting hexadecimal digits. The precision specifier controls the minimum number of digits in the resulting string: PS > "{0:X4}" -f 1324 052C

Custom Numeric Format Strings

You can use custom numeric strings, listed in Table 4-2, to format numbers in ways not supported by the standard format strings.

Table 4-2. Custom numeric format strings

Format specifier	Name	Description
0	Zero placeholder	Specifies the precision and width of a number string. Zeros not matched by digits in the original number are output as zeros: PS > "{0:00.0}" -f 4.12341234 04.1
#	Digit placeholder	Specifies the precision and width of a number string. # symbols not matched by digits in the input number are not output: PS > "{0:##.#}" -f 4.12341234 4.1
.	Decimal point	Determines the location of the decimal: PS > "{0:##.#}" -f 4.12341234 4.1
,	Thousands separator	When placed between a zero or digit placeholder before the decimal point in a formatting string, adds the separator character between number groups: PS > "{0:#,#.#}" -f 1234.121234 1,234.1
,	Number scaling	When placed before the literal (or implicit) decimal point in a formatting string, divides the input by 1,000. You can apply this format specifier more than once: PS > "{0:##,,.000}" -f 1048576 1.049
%	Percentage placeholder	Multiplies the input by 100, and inserts the percent sign where shown in the format specifier: PS > "{0:%##.000}" -f .68 %68.000
E0 E+0 E-0 e0 e+0 e-0	Scientific notation	Displays the input in scientific notation. The number of zeros that follow the E define the minimum length of the exponent field: PS > "{0:##.#E000}" -f 2.71828 27.2E-001
' text ' " text "	Literal string	Inserts the provided text literally into the output without affecting formatting: PS > "{0:#.00'##'}" -f 2.71828 2.72##
;	Section separator	Allows for conditional formatting. If your format specifier contains no section separators, the formatting statement applies to all input. If your format specifier contains one separator (creating two sections), the first section applies to positive numbers and zero, and the second section applies to negative numbers. If your format specifier contains two separators (creating three sections), the sections apply to positive numbers, negative numbers, and zero: PS > "{0:POS;NEG;ZERO}" -f -14 NEG
Other	Other character	Inserts the provided text literally into the output without affecting formatting: PS > "{0:$## Please}" -f 14 $14 Please