3.2 Formatting Strings

Given one or more objects, you want to create a single formatted string representation.

Technique

You can format strings using numeric and picture formatting within String.Format or within any method that uses string-formatting techniques for parameters such as Console.WriteLine .

Comments

The String class as well as a few other methods within the .NET Framework allow you to format strings to present them in a more ordered and readable format. Up to this point in the book, we used basic formatting when calling the Console.WriteLine method. The first parameter to Console.WriteLine is the format specifier string. This string controls how the remaining parameters to the method should appear when displayed. You use placeholders within the format string to insert the value of a variable. This placeholder uses the syntax { n } where n is the index in the parameter list following the format specifier. Take the following line of code, for instance:

 Console.WriteLine( "x={0}, y={1}, {0}+{1}={2}", x, y, x+y ); 

This line of code has three parameters following the format specifier string. You use placeholders within the format specification, and when this method is called, the appropriate substitutions are made. Although you can do the same thing using string concatenation, the resultant line of code is slightly obfuscated :

 string s = "x=" + x + ",y=" + y + ", " + x + "+" + y + "=" + (x+y); Console.WriteLine( s ); 

You can further refine the format by applying format attributes on the placeholders themselves . These additional attributes follow the parameter index value and are separated from that index with a : character. There are two types of special formatting available. The first is numeric formatting, which lets you format a numeric parameter into one of nine different numeric formats, as shown in Table 3.1. The format of these specifiers, using the currency format as an example, is C xx where xx is a number from 1 to 99 specifying the number of digits to display. Listing 3.2 shows how to display an array of integers in hexadecimal format, including how to specify the number of digits to display. Notice also how you can change the case of the hexadecimal numbers A through F by using an uppercase or lowercase format specifier.

Table 3.1. Numeric Formatting Specifiers

Character	Format	Description
C or c	Currency	Culturally aware currency format.
D or d	Decimal	Only supports integral numbers. Displays a string using decimal digits preceded by a minus sign if negative.
E or e	Exponential/scientific notation	Displays numbers in the form ± d.dddddd E ± dd where d is a decimal digit.
F or f	Fixed point	Displays a series of decimal digits with a decimal point and additional digits.
G or g	General format	Displays either as a fixed-point or scientific notation based on the size of the number.
N or n	Number format	Similar to fixed point but uses a separator character (such as , ) for groups of digits.
P or p	Percentage	Multiplies the number by 100 and displays with a percent symbol.
R or r	Roundtrip	Formats a floating-point number so that it can be successfully converted back to its original value.
X or x	Hexadecimal	Displays an integral number using the base-16 number system.

Listing 3.2 Specifying a Different Numeric Format by Adding Format Specifiers on a Parameter Placeholder

 using System; namespace _2_Formatting {     class Class1     {         [STAThread]         static void Main(string[] args)         {             double[] numArray = {2, 5, 4.5, 45.43, 200000};             // format in lowercase hex             Console.WriteLine( "\n\nHex (lower)\n-----------" );             foreach( double num in numArray )             {                 Console.Write( "0x{0:x}\t", (int) num );             }             // format in uppercase hex             Console.WriteLine( "\n\nHex (upper)\n-----------" );             foreach( double num in numArray )             {                 Console.Write( "0x{0:X}\t", (int) num );             }         }     } } 

Another type of formatting is picture formatting. Picture formatting allows you to create a custom format specifier using various symbols within the format specifier string. Table 3.2 lists the available picture format characters. Listing 3.3 also shows how to create a custom format specifier. In that code, the digits of the input number are extracted and displayed using a combination of digit placeholders and a decimal-point specifier. Furthermore, you can see that you are free to add characters not listed in the table. This freedom allows you to add literal characters intermixed with the digits.

Table 3.2. Picture Formatting Specifiers

Character	Name	Description
	Zero placeholder	Copies a digit to the result string if a digit is at the position of the . If no digit is present, a 0 is displayed.
#	Display digit placeholder	Copies a digit to the result string if a digit appears at the position of the # . If no digit is present, nothing is displayed.
.	Decimal point	Represents the location of the decimal point in the resultant string.
,	Group separator and number scaling	Inserts thousands separators if placed between two placeholders or scales a number down by 1,000 per , character when placed directly to the left of a decimal point.
&	Percent	Multiplies a number by 100 and inserts a % symbol.
E ±0 , e ±0	Exponential notation	Displays the number in exponential notation using the number of 0s as a placeholder for the exponent value.
\	Escape character	Used to specify a special escape-character formatting instruction. Some of these include \n for newline, \t for tab, and \\ for the \ character.
;	Section separator	Separates positive, negative, and zero numbers in the format string in which you can apply different formatting rules based on the sign of the original number.

Listing 3.3 shows how custom formatting can separate a number by its decimal point. Using a foreach loop, each value is printed using three different formats. The first format will output the value's integer portion using the following format string:

 0:$#,# 

Next, the decimal portion is written. If the value does not explicitly define a decimal portion, zeroes are written instead. The format string to output the decimal value is

 $.#0; 

Finally, the entire value is displayed up to two decimal places using the following format string:

 {0:$#,#.00} 

Listing 3.3 Using Picture Format Specifiers to Create Special Formats

 using System; namespace _2_Formatting {     class Class1     {         [STAThread]         static void Main(string[] args)         {             double[] numArray = {2, 5, 4.5, 45.43, 200000};             // format as custom             Console.WriteLine( "\n\nCustom\n------" );             foreach( double num in numArray )             {                 Console.WriteLine( "{0:$#,# + $.#0;} = {0:$#,#.00}", num );             }         }     } }