Feb 8 2006

String Formatting in C#

Category:Bil@l @ 07:45

String Formatting in C#

I couldn’t find a quick reference to .NET string formatting using the String.Format() function, so I created this one.

When I started working with the .NET framework, one thing puzzled me. I couldn’t find sprintf(). sprintf() is the C function that takes an output buffer, a format string, and any number of arguments, and builds a string for you. For example:

char szError[256];
sprintf(szError, “Error %d occurred.\n”, nError);

This would write “Error 12 occurred.” into the szError buffer (assuming nError was 12). It’s a basic part of C programming and most C++ programmers still use it though better functionality is available in the STL because sprintf is simple to use and clear. The STL equivalent would be:

str << “Error ” << nError << ” occurred.” << endl;

Or something close to that. It’s type-safe, and more OO than sprintf, but not as easy to read and not as easy to localize.

The .NET framework handles strings very nicely - but it takes some getting used to. The rough equivalent of sprintf in .NET is the static String.Format function, which takes a format string and some arguments, and generates an output string. (This is a nice improvement over sprintf since there’s no chance you’ll overflow the output buffer). For example:

string errorString = String.Format(”Error {0} occurred.”, nError);

Teeming with metadata, the .NET environment doesn’t need the format string to say what type of data you’re formatting, just where you want it. (A common sprintf bug is supplying the wrong data type - there’s no protection from using %s instead of %d and having your program crash when sprintf is called).

The {0} in the string above is replaced with the value of nError, but what if you want to specify the number of digits to use? Or the base (hexadecimal etc)? The framework supports all this, but where it seemed confusing is that it’s not the String.Format function that does the string formatting, but rather the types themselves.

Every object has a method called ToString that returns a string representation of the object. The ToString method can accept a string parameter, which tells the object how to format itself - in the String.Format call, the formatting string is passed after the position, for example, “{0:##}”

The text inside the curly braces is {index[,alignment][:formatString]}. If alignment is positive, the text is right-aligned in a field the given number of spaces; if it’s negative, it’s left-aligned.


There really isn’t any formatting within a strong, beyond it’s alignment. Alignment works for any argument being printed in a String.Format call.

Sample Generates
String.Format(”->{1,10}<-”, “Hello”); -> Hello<-
String.Format(”->{1,-10}<-”, “Hello”); ->Hello <-


Basic number formatting specifiers:

Specifier Type Format Output (Passed Double 1.42) Output (Passed Int -12400)
c Currency {0:c} $1.42 -$12,400
d Decimal (Whole number) {0:d} System.FormatException -12400
e Scientific {0:e} 1.420000e+000 -1.240000e+004
f Fixed point {0:f} 1.42 -12400.00
g General {0:g} 1.42 -12400
n Number with commas for thousands {0:n} 1.42 -12,400
r Round trippable {0:r} 1.42 System.FormatException
x Hexadecimal {0:x4} System.FormatException cf90

Custom number formatting:

Specifier Type Example Output (Passed Double 1500.42) Note
0 Zero placeholder {0:00.0000} 1500.4200 Pads with zeroes.
# Digit placeholder {0:(#).##} (1500).42
. Decimal point {0:0.0} 1500.4
, Thousand separator {0:0,0} 1,500 Must be between two zeroes.
,. Number scaling {0:0,.} 2 Comma adjacent to Period scales by 1000.
% Percent {0:0%} 150042% Multiplies by 100, adds % sign.
e Exponent placeholder {0:00e+0} 15e+2 Many exponent formats available.
; Group separator see below

The group separator is especially useful for formatting currency values which require that negative values be enclosed in parentheses. This currency formatting example at the bottom of this document makes it obvious:


Note that date formatting is especially dependant on the system’s regional settings; the example strings here are from my local locale.

Specifier Type Example (Passed System.DateTime.Now)
d Short date 10/12/2002
D Long date December 10, 2002
t Short time 10:11 PM
T Long time 10:11:29 PM
f Full date & time December 10, 2002 10:11 PM
F Full date & time (long) December 10, 2002 10:11:29 PM
g Default date & time 10/12/2002 10:11 PM
G Default date & time (long) 10/12/2002 10:11:29 PM
M Month day pattern December 10
r RFC1123 date string Tue, 10 Dec 2002 22:11:29 GMT
s Sortable date string 2002-12-10T22:11:29
u Universal sortable, local time 2002-12-10 22:13:50Z
U Universal sortable, GMT December 11, 2002 3:13:50 AM
Y Year month pattern December, 2002

The ‘U’ specifier seems broken; that string certainly isn’t sortable.

Custom date formatting:

Specifier Type Example Example Output
dd Day {0:dd} 10
ddd Day name {0:ddd} Tue
dddd Full day name {0:dddd} Tuesday
f, ff, … Second fractions {0:fff} 932
gg, … Era {0:gg} A.D.
hh 2 digit hour {0:hh} 10
HH 2 digit hour, 24hr format {0:HH} 22
mm Minute 00-59 {0:mm} 38
MM Month 01-12 {0:MM} 12
MMM Month abbreviation {0:MMM} Dec
MMMM Full month name {0:MMMM} December
ss Seconds 00-59 {0:ss} 46
tt AM or PM {0:tt} PM
yy Year, 2 digits {0:yy} 02
yyyy Year {0:yyyy} 2002
zz Timezone offset, 2 digits {0:zz} -05
zzz Full timezone offset {0:zzz} -05:00
: Separator {0:hh:mm:ss} 10:43:20
/ Separator {0:dd/MM/yyyy} 10/12/2002


Specifier Type
g Default (Flag names if available, otherwise decimal)
f Flags always
d Integer always
x Eight digit hex.

Some Useful Examples

String.Format(”{0:$#,##0.00;($#,##0.00);Zero}”, value);

This will output “$1,240.00? if passed 1243.50. It will output the same format but in parentheses if the number is negative, and will output the string “Zero” if the number is zero.

String.Format(”{0:(###) ###-####}”, 8005551212);

This will output “(800) 555-1212?.

If you have any questions about string formatting, or pretty much anything related, drop by the Forum and ask it there. It’s an easier place to talk than in the comments section here.

14 Responses to “String Formatting in C#”

  1. stevex » Blog Archive » Different Theme Says:

    […] In case anyone reads this on the main page instead of in an aggregator.. I’m trying out a different theme. It’s wider, so code snippets don’t wrap. I wanted to make my String Formatting in C# page look good since searching for how to do sprintf type formatting in C# is how most people find this site. […]

  2. pwalls Says:

    Great resource! This is definitely a handy reference page I’ve added to my favorites. However, I did notice a minor error.

    The following:

    String.Format(”{0:(###) ###-####}”, 18005551212);

    Produces (1800) 555-1212 and not (800) 555-1212.

    Otherwise, great information.

  3. Tim Lewis Says:

    This will output “$1,240.00? if passed 1243.50. It will output the same format but in parentheses if the number is negative, and will output the string “Zero” if the number is zero.

    String.Format(”{0:$#,##0.00;($#,##0.00);Zero}”, 1243.50); // Outputs “$1,243.50? not the claimed “$1,240.00?

  4. Max Says:

    I want format String



  5. murugan.g Says:

    Hi Steve,

    Thanks for this wonderful article.

    How can i format date like this “December 08th, 2005?.

  6. Jorge de Cardenas Says:

    Someone asked if 0,1 could be formatted to no,yes on your other page

    this can be done with formatting using:

    String.Format(”{0:yes;;no}”, value)

    => yes if value == 1
    => no if value == 0

  7. Jeremy Says:

    Was this article ripped off from here:



    I ask because they are almost identical.

  8. stevex Says:

    Nope.. it looks like they’re just surprisingly coincidentally similar. My original article was posted in 2003, over here:


    His was posted 2004.

  9. Krise Says:

    Nice howto,
    there is a small error in it though:

    the following :

    Sample Generates
    String.Format(”->{1,10} Hello{1,-10}Hello

  10. Broads Says:


    I have found this blog very usefull but was wondering if you may shed some light on the following.
    I have a shopping basket on my site which should display my total as GBP £x.xx however when using the string.format {0:c} the currency of the hosting server is used. So when I developed and tested my site all looked fine. When I then hosted my site it took, i presume, the localisation of the hosts server and displayed as $x.xx

    To get around this I am now using string.format{0:#.##} which is then prefixed with a physical £ sign.

    Is this the correct way to get over this formating issue or is there a better way.


  11. Philippe Quesnel Says:

    great info ! at last, I always swear at the .NET doc when looking form string formatting info ;-)

    note: the 1st example, right at the top of the article:
    String.Format(”->{1,10} Hello{1,-10}Hello

  12. Philippe Quesnel Says:

    oops, sorry, don’t know what happened to my text in the 1st post !! ??

    here it is again, hopefully complete this time !

    great info ! at last, I always swear at the .NET doc when looking form string formatting info ;-)

    note: the 1st example, right at the top of the article:
    String.Format(”->{1,10} Hello{1,-10}Hello

  13. tom callaghan Says:

    I know there is a way to do this, I just cannot remember the format string. I want to force a sign place holder so that either ‘+’ for positive numbers or ‘-’ for negative numbers will print. For example

    34.2 outputs as +34.2 and -34.2 outputs as -34.2

  14. ddegenaro Says:

    if i have converted from like “1110.20? to “$1,110.20? using {0:C}
    how do i convert “$1,110.20? back to “1110.20?..i tried {0:f} and {0:0.00}
    still doesnt work!


Comments are closed