String concatenation is a common aspect of almost every development effort. However, the combination of single and double quotes, along with escape characters, text, and plus signs (+) can be a bit overwhelming. The .NET Framework provides a much cleaner approach with the String class's Format method. It allows you to create string values by specifying insertion points for other values as well as special formatting.

Syntax

This String.Format method accepts a format string followed by one to many variables that are to be formatted. The format string consists of placeholders, which are essentially locations to place the value of the variables you pass into the function. These placeholders have the following format:

{indexNumber:formatCharacter}

The matching braces ("{" and "}") are required. Because opening and closing braces are interpreted as starting and ending a format item, you must specify two opening braces ("{{") in the fixed text to display one opening brace ("{"), and specify two closing braces ("}}") in the fixed text to display one closing brace ("}").

The mandatory index component, also called a parameter specifier, is a number starting at zero. It identifies a corresponding element in the list of values. That is, the format item whose parameter specifier is zero formats the first value in the list, the format item whose parameter specifier is the one that formats the second value in the list, and so on. Multiple format items can refer to the same element in the list of values by specifying the same parameter specifier.

Each format item can refer to any parameter. For example, if there are three values, you can format the second, first, and third value by specifying a source string like this: "{1} {0} {2}". A value that isn't referenced by a format item is ignored. A runtime exception results if a parameter specifier designates an item outside the bounds of the list of values.

The .NET Framework defines numerous options for formatting a string value according to the desired type. The following list contains a sampling of legal values for the formatCharacter portion of the format string (if used) for numeric values:

  • C or c: The number is converted to a string that represents a currency amount.
  • D or d: The number is converted to a string of decimal digits (0-9), prefixed by a minus sign if the number is negative. The precision specifier indicates the minimum number of digits desired in the resulting string. If required, the number is padded with zeros to its left to produce the number of digits given by the precision specifier.
  • E or e: The number is converted to a string of the form "-d.ddd...E+ddd" or "-d.ddd...e+ddd", where each 'd' indicates a digit (0-9). The string starts with a minus sign if the number is negative. One digit always precedes the decimal point. The precision specifier indicates the desired number of digits after the decimal point.
  • F or f: The number is converted to a string of the form "-ddd.ddd..." where each 'd' indicates a digit (0-9).
  • G or g: The number is converted to the most compact of either fixed-point or scientific notation, depending on the type of the number and whether a precision specifier is present.
  • N or n: The number is converted to a string of the form "-d,ddd,ddd.ddd...", where each 'd' indicates a digit (0-9).
  • P or p: The number is converted to a string that represents a percent.
  • X or x: The number is converted to a string of hexadecimal digits.

Using these options, the following VB.NET code would display $10.99.

Dim price As Integer
price = 10
Console.WriteLine(String.Format("{0:c}", price))

The String.Format line tells the system to take the first variable (zero) from the list and format it as currency (c). Now the currency symbol ($) displayed depends on the global locale settings. This approach is much easier to code and follow than the alternative method using concatenation that requires you to add the necessary decimal point and zeroes:

Console.WriteLine("$" + price.ToString() + ".00")

The String.Format approach allows the code to stay the same no matter the numeric type utilized. Likewise, the hexadecimal equivalent of a numeric value can easily be displayed

Dim hex As Long
hex = 100
Console.WriteLine(String.Format("{0:x}", hex))

If you're familiar with the hexadecimal number system, then you know 64 will be displayed. The equivalent C# code for the previous two listings follows:

int price;
price = 10;
Console.WriteLine(String.Format("{0:c}", price));
long hex;
hex = 100;
Console.WriteLine(String.Format("{0:x}", hex));

The Format method isn't restricted to numeric values. The next list contains a sampling of the options for formatting date-time values.

  • d: The value is converted to the short date pattern.
  • D: The value is converted to the long date pattern.
  • t: The value is converted to the short time pattern.
  • T: The value is converted to the long time pattern.
  • f: The value is converted to the full date-time pattern, including short time.
  • F: The value is converted to the full date-time pattern, including long time.
  • g: The value is converted to the short date and short time.
  • G: The value is converted to the long date and long time.
  • M or m: The value is converted to the month day pattern.

Working with date values is no different than numbers. The following VB.NET example displays today's date using the long date pattern:

Dim dt As DateTime
dt = DateTime.Now
Console.WriteLine(String.Format("Today's date is {0:D}", dt))

The output displayed (on my machine) is:

Today's date is January 25, 2005

If you only want the current time portion, this is the code you would use:

Dim dt As DateTime
dt = DateTime.Now
Console.WriteLine(String.Format("The current time is {0:T}", dt))

Here's the C# equivalent:

DateTime dt;
dt = DateTime.Now;
Console.WriteLine(String.Format("Today's date is {0:D}", dt));
Console.WriteLine(String.Format("The current time is {0:T}", dt));

Only the beginning

The built-in format options allow you to easily format values according to application requirements, but you aren't restricted to these options. The .NET environment allows you to specify a custom format as well.

TechRepublic's free .NET newsletter, delivered each Wednesday, contains useful tips and coding examples on topics such as Web services, ASP.NET, ADO.NET, and Visual Studio .NET. Automatically sign up today!