.NET STRING FORMATTING IN C# CHEAT SHEET
String formatting in .NET C# is easy – the hard part is looking up what all the formatting specifiers do. I find myself constantly checking the (rather wordy) .NET documentation just to format a date or a currency value. This cheat sheet brings all the String.Format formatting specifiers together in one easy overview.
How to format
The String.Format method is your friend. It can format any number of arguments into a string, like so:
String.Format("{0} and {1} is {2}", 2, 2, 2+2)which returns
2 and 2 is 4Wherever you want String.Format to insert a formatted value, place curly braces containing the index of the argument (0 being the first argument, 1 being the second and so on). The String.Format method will format your arguments according to its default formatting rules (depending on the argument types) and place them in the result string. But what if you want your values formatted in a special way? You use formatting specifiers like so:
String.Format("{0:c}", 3.456)returns
$3.46In other words, you place a colon and a formatting specifier after the argument index.
Formatting Numbers
Standard Numeric Format Strings
| Specifier | Type | Format | Sample (36.45) | Sample (-12345) |
|---|---|---|---|---|
| c/C | Currency | {0:c} | $36.45 | (-$12,345.00) |
| d/D | Decimal | {0:d} | Exception | -12345 |
| e/E | Scientific | {0:e} | 3.645000e+001 | -1.234500e+004 |
| f/F | Fixed-point | {0:f} | 36.45 | -12345.00 |
| g/G | General | {0:g} | 36.45 | -12345 |
| n/N | Number with thousand separator | {0:n} | 36.45 | -12,345.00 |
| p/P | Percentage | {0:0} | 3,645.00 % | 1,234,500.00 % |
| r/R | Round-trip | {0:r} | 36.45 | Exception |
| x/X | Hexadecimal | {0:x} | Exception | fffcfc7 |
- Round-trip formatting is converting a number to a string in such a way that it can be converted back into the same number. This conversion is only supported for single and double types.
- Currency conversion will use the currency symbol, thousands and decimal separators specified by the current Culture.
- Percentage conversion multiplies the number by 100, then adds a percentage sign.
Precision
Each number formatting specifier can be accompanied by a precision (if omitted, the default precision is assumed):
| Specifier | Type | Format | Precision specifier function | Default precision | Sample (precision 6) | Result |
|---|---|---|---|---|---|---|
| c/C | Currency | {0:c6} | Number of decimal digits | Defined by System.Globalization.NumberFormatInfo | 3.45 | $3.450000 |
| d/D | Decimal | {0:d6} | Minimum number of digits | Minimum number of digits required | 123 | 000123 |
| e/E | Scientific | {0:e6} | Number of decimal digits | 6 | 3.45 | 3.450000e+000 |
| f/F | Fixed-point | {0:f6} | Number of decimal digits | Defined by System.Globalization.NumberFormatInfo | 3.45 | 3.450000 |
| g/G | General | {0:g6} | Number of significant digits | Depends on numeric type | 3.35 | 3.45 |
| n/N | Number with thousand separator | {0:n6} | Desired number of decimal places | Defined by System.Globalization.NumberFormatInfo | 3.45 | 3.450000 |
| p/P | Percentage | {0:p6} | Desired number of decimal places | Defined by System.Globalization.NumberFormatInfo | 0.345 | 34.500000 % |
| r/R | Round-trip | {0:r6} | Ignored | 3.45 | 3.45 | |
| x/X | Hexadecimal | {0:x6} | Number of digits in the result string | 345 | 000159 |
Custom Number Formatting
Beyond the standard numeric format strings, you can define your own specific formatting. You can mix and match the following:
| Specifier | Type | Sample | Value | Result |
|---|---|---|---|---|
| 0 | Zero placeholder | {0:0000.0000} | 3.45 | 00003.4500 |
| # | Digit placeholder | {0:#####:##} | 531.456 | 531.45 |
| . | Decimal separator | {0:0,000.00} | 1234.45 | 1,234.45 |
| , | Thousands separator | {0:0,000.00} | 1234.45 | 1,234.45 |
| % | Percent sign | {0:0.00%} | 0.45 | 45.00% |
- The zero placeholder allows you to pad a number with zeroes.
- The percent sign multiplies a value by 100, then adds a percent sign.
Formatting Dates
| Specifier | Type | Sample |
|---|---|---|
| d | Short date | 08/03/2013 |
| D | Long date | Friday, March 08, 2013 |
| f | Full date and time, short | Friday, March 08, 2013 10:10 AM |
| F | Full date and time, long | Friday, March 08, 2013 10:10:44 |
| g | Default date and time | 08/03/2013 10:10 AM |
| M | Month and day | March 08 |
| r | RFC1123 date | Fri, 08 Mar 2013 10:10:44 GMT |
| s | Sortable date string | 2013-03-08T10:10:44 |
| t | Short time | 10:10 AM |
| T | Long time | 10:10:44 |
| u | Universal sortable local time | 2013-03-08 10:10:44Z |
| U | Universal GMT | Friday, March 08, 2013 08:10:44 |
| Y | Month and year | March, 2013 |
Custom Date Formatting
| Specifier | Meaning | Sample | Result |
|---|---|---|---|
| d | Day, zero-padded | {0:dd} | 08 |
| ddd | 3-letter day name | {0:ddd} | Fri |
| dddd | Full day name | {0:dddd} | Friday |
| ff | Second fractions, 2 digits | {0:ff} | 19 |
| fff | Second fractions, 3 digits | {0:fff} | 193 |
| ffff | Second fractions, 4 digits | {0:ffff} | 1934 |
| gg | Era | {0:gg} | A.D. |
| hh | Hour (2 digits, 12H) | {0:hh} | 10 |
| HH | Hour (2 digits, 24H) | {0:HH} | 10 |
| mm | Minutes, zero-padded | {0:mm} | 16 |
| MM | Month, zero-padded | {0:MM} | 03 |
| MMM | 3-letter month name | {0:MMM} | Mar |
| MMMM | Full month name | {0:MMMM} | March |
| ss | Seconds | {0:ss} | 02 |
| tt | AM/PM | {0:tt} | AM |
| yy | 2-digit year | {0:yy} | 13 |
| yyyy | 4-digit year | {0:yyyy} | 2013 |
| zz | 2-digit timezone offset | {0:zz} | +02 |
| zzz | Full timezone offset | {0:zzz} | +02:00 |
Usage
You can now place various custom date formatting specifiers in a formatting string like so:
String.Format("{0:hh:mm tt, ddd-MM-MMM yyyy gg}", DateTime.Now)which yields
10:26 AM, Fri-03-Mar 2013 A.D.