Formatting Strings in C# with String.Format

String.Format is a very powerful method but the documentation at MSDN is quite wordy and spreads the details over many pages. For this post I have made quick reference to its many specifiers and for good measure added some examples to help get you started.If you would like to format a date, currency, number or just the time, String.Format is your friend.

For a trip down memory lane a little example how we did things in C. The C sprintf function takes a buffer, a formatting string, a couple of parameters and munches them together:

#include <stdio.h>
int main()
{
char buffer[255];
sprintf(buffer,"Customer %d lives is %d years old and owns us %2.2f dollars", 1024, 96, 125.6f);
printf("%s",buffer);
}

This results in the following output:

Customer 1024 is 96 years old and owns us 125.50

Of course, if we made the buffer too small and the string expanded too much we might have created a buffer overrun once of C’s pesky little annoyances. And of course for each parameter we need to specify how to format them (%d for integers, %s for strings and %f for floats). Get the type wrong and things will go funny fast.

Enter String.Format and Console.WriteLine

So how do things work in C#? The String.Format method takes care of all our needs and a little more. Similar to the relationships between sprintf and printf the methods String.Format and Console.WriteLine work similary. String.Format returns a string whereas Console.WriteLine sends the resulting string to the console output.

The following should be a familiar example:

int ResultValue = 123;
string myString = String.Format(“The value is {0}”,ResultValue);
Console.WriteLine(“The value is {0}”,ResultValue);

The Index

The {0} is an index and refers to the first parameter given following the formatting string. {1},{2} to the second, third etc. You can also refer to a parameter more than once. The following is perfectly acceptable:

Console.WriteLine(“First {0}, Second {1}, Third {2}, And again the First {0}”,Value1,Value2,Value2);

Aligning the output

C# provides an alignment value that allows you to left or right align the output. Handy for screen or print formatting.

If you specify an alignment of 10 characters the resulting string will always be 10 characters even if the number only took up 4 places. The remainder is padded with spaces. If the value we want to display is longer than our given alignment size the alignment value is ignored.

Console.WriteLine(“The value is {0,10} – continue from here”,9999);

The above will output the value “9999″, and allocate 10 spaces for it. The output is right-aligned, the format method will simply add sufficient spaces to make sure the total length adds up to 10 characters.

To make the output left-aligned we need to make the number negative:

Console.WriteLine(“The value is {0,-10} – continue from here”,9999);

Displaying enumerated types

One very interesting feature of C# is the ability to display enumerated types.If you make your own enumeration wouldn’t it be nice if you could just print the values as a string literals? In fact you can as shown by the following example:

class MainClass
{
public enum Transport {Car = 1, Plane = 2, Motorcycle = 3}

public static void Main(string[] args)
{
Transport peopleMover = Transport.Plane;

Console.WriteLine("{0:G}",peopleMover);  // string literal
Console.WriteLine("{0:f}",peopleMover);   // flag -- not clear
Console.WriteLine("{0:d}",peopleMover);  // decimal
Console.WriteLine("{0:x}",peopleMover);   // hexadecimal
}
}

This outputs:

Plane

Plane

2
00000002

Basic number formatting

When no format is specified the String.Format method applies the “g” (General) type, which results in any value passed being rendered into a standard string. The following table shows what is possible:

If the table lists (error) it means that the String.Format method threw a String.Formatting exception. This happens if the number cannot be converted properly.

Custom number formatting

Of course, your preferred format is not listed above and you need a few modifications made. Not a problem. Custom formatting allows for any kind of number-to-string conversion you might need:

Date formats

The following table show the basic date formats obtained from calling DateTime.Now and then formatting the result. Note that different systems might produce different results depending on how the operating system is configured (think Chinese/Japanese/etc systems).

Custom Date formatting

The custom format strings allow DateTime objects to be formatted when the standard formatting strings are not useful and you need some special.

Image credit: easement

This is a post from Martijn's C# Coding Blog.