Formatting
Format
| Function | Parameters | Return value |
|---|---|---|
Format |
string format, params object[] args |
string |
Replaces the format item in a specified format string with the value of a corresponding Object instance in a specified args array.
For example, the following function call:
Format("Name = {0}, hours = {1:hh}", myName, DateTime.Now)
contains the following format items: {0} and {1:hh}. They will be replaced with values of myName and DateTime.Now. The result may look as follows:
Name = Alex, hours = 12
Each format item takes the following form:
{index[,alignment][:formatString]}
index- a zero-based integer that indicates which element in a list of objects to format;alignment- an optional integer indicating the minimum width of the region to contain the formatted value. If the length of the formatted value is less than alignment, then the region is padded with spaces. If alignment is negative, the formatted value is left justified in the region; if alignment is positive, the formatted value is right justified;formatString- an optional string of format specifiers.
The following table describes the standard numeric format strings.
| Format Specifier | Name | Description |
|---|---|---|
| C or c | Currency | The number is converted to a string that represents a currency amount.Format("{0:C}", 10) = "$10.00" |
| D or d | Decimal | This format is supported for integral types only. The number is converted to a string of decimal digits (0-9).Format("{0:D}", 10) = "10" |
| E or e | Scientific | 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).Format("{0:E}", 10) = "1.000000E+001" |
| F or f | Fixed-point | The number is converted to a string of the form -ddd.ddd… where each d indicates a digit (0-9).Format("{0:F}", 10) = "10.00" |
| G or g | General | The number is converted to the most compact notation.Format("{0:G}", 10) = "10" |
| N or n | Number | The number is converted to a string of the form -d,ddd,ddd.ddd…, where each d indicates a digit (0-9).Format("{0:N}", 1234.56) = "1,234.56" |
| P or p | Percent | The number is converted to a string that represents a percent. The converted number is multiplied by 100 in order to be presented as a percentage.Format("{0:P}", 0.15) = "15.00%" |
| X or x | Hexadecimal | The number is converted to a string of hexadecimal digits. The case of the format specifier indicates whether to use uppercase or lowercase characters for the hexadecimal digits greater than 9. For example, use X to produce ABCDEF, and x to produce abcdef.Format("{0:X}", 26) = "1A" |
If you format the floating-point values, you may indicate a number of decimal places after the format string:
Format("{0:C1}", 12.23) = "$12.2"
If the standard numeric format specifiers do not provide the type of formatting you require, you can use custom format strings:
| Format character | Description |
|---|---|
| 0 | Zero placeholder. If the value being formatted has a digit in the position where the 0 appears in the format string, then that digit is copied to the result string. The position of the leftmost 0 before the decimal point and the rightmost 0 after the decimal point determines the range of digits that are always present in the result string. |
| # | Digit placeholder. If the value being formatted has a digit in the position where the # appears in the format string, then that digit is copied to the result string. Otherwise, nothing is stored in that position in the result string. |
| . | Decimal point. The first . character in the format string determines the location of the decimal separator in the formatted value. |
| , | Thousand separator. If the format string contains a , character, then the output will have thousand separators inserted between each group of three digits to the left of the decimal separator. |
| % | Percentage placeholder. The presence of a % character in a format string causes a number to be multiplied by 100 before it is formatted. |
| ; | Section separator. The ; character is used to separate sections for positive, negative, and zero numbers in the format string. |
Examples of use:
Format("{0:$#,##0.00}", 1024.25) = "$1,024.25"
Format("{0:00%}", 0.25) = "25%"
Format("{0:$#,##0.00;($#,##0.00);Zero}", 1024.25) = "$1,024.25"
Format("{0:$#,##0.00;($#,##0.00);Zero}", -1024.25) = "($1,024.25)"
Format("{0:$#,##0.00;($#,##0.00);Zero}", 0) = "Zero"
The following table describes the standard format specifiers for formatting the DateTime values:
| Format Specifier | Name | Example |
|---|---|---|
| d | Short date pattern | "4/2/2024" |
| D | Long date pattern | "Tuesday, April 2, 2024" |
| f | Full date/time pattern (short time) | "Tuesday, April 2, 2024 8:41 PM" |
| F | Full date/time pattern (long time) | "Tuesday, April 2, 2024 8:41:01 PM" |
| g | General date/time pattern (short time) | "4/2/2024 8:41 PM" |
| G | General date/time pattern (long time) | "4/2/2024 8:41:01 PM" |
| t | Short time pattern | "8:41 PM" |
| T | Long time pattern | "8:41:01 PM" |
The following table describes the custom date/time format specifiers and the results they produce.
| Format Specifier | Description |
|---|---|
| d | Displays the current day of the month, measured as a number between 1 and 31, inclusive. If the day is a single digit only (1-9), then it is displayed as a single digit. |
| dd | Displays the current day of the month, measured as a number between 1 and 31, inclusive. If the day is a single digit only (1-9), it is formatted with a preceding 0 (01-09). |
| ddd | Displays the abbreviated name of the day. |
| dddd | Displays the full name of the day. |
| f or F | Displays the most significant digit of the seconds fraction. |
| h | Displays the hour in the range 1-12. If the hour is a single digit (1-9), it is displayed as a single digit. |
| hh | Displays the hour in the range 1-12. If the hour is a single digit (1-9), it is formatted with a preceding 0 (01-09). |
| H | Displays the hour in the range 0-23. If the hour is a single digit (1-9), it is displayed as a single digit. |
| HH | Displays the hour in the range 0-23. If the hour is a single digit (1-9), it is formatted with a preceding 0 (01-09). |
| m | Displays the minute in the range 0-59. If the minute is a single digit (0-9), it is displayed as a single digit. |
| mm | Displays the minute in the range 0-59. If the minute is a single digit (0-9), it is formatted with a preceding 0 (01-09). |
| M | Displays the month, measured as a number between 1 and 12, inclusive. If the month is a single digit (1-9), it is displayed as a single digit. |
| MM | Displays the month, measured as a number between 1 and 12, inclusive. If the month is a single digit (1-9), it is formatted with a preceding 0 (01-09). |
| MMM | Displays the abbreviated name of the month. |
| MMMM | Displays the full name of the month. |
| s | Displays the seconds in the range 0-59. If the second is a single digit (0-9), it is displayed as a single digit only. |
| ss | Displays the seconds in the range 0-59. If the second is a single digit (0-9), it is formatted with a preceding 0 (01-09). |
| t | Displays the first character of the A.M./P.M. designator. |
| tt | Displays the A.M./P.M. designator. |
| y | Displays the year as a maximum two-digit number. The first two digits of the year are omitted. If the year is a single digit (1-9), it is displayed as a single digit. |
| yy | Displays the year as a maximum two-digit number. The first two digits of the year are omitted. If the year is a single digit (1-9), it is formatted with a preceding 0 (01-09). |
| yyyy | Displays the year, including the century. If the year is less than four digits in length, then preceding zeros are appended as necessary to make the displayed year four digits long. |
| z | Displays the time zone offset for the system's current time zone in whole hours only. The offset is always displayed with a leading sign (zero is displayed as "+0"), indicating hours ahead of Greenwich mean time (+) or hours behind Greenwich mean time (-). The range of values is –12 to +13. If the offset is a single digit (0-9), it is displayed as a single digit with the appropriate leading sign. |
| zz | Displays the time zone offset for the system's current time zone in whole hours only. The offset is always displayed with a leading or trailing sign (zero is displayed as "+00"), indicating hours ahead of Greenwich mean time (+) or hours behind Greenwich mean time (-). The range of values is –12 to +13. If the offset is a single digit (0-9), it is formatted with a preceding 0 (01-09) with the appropriate leading sign. |
| zzz | Displays the time zone offset for the system's current time zone in hours and minutes. The offset is always displayed with a leading or trailing sign (zero is displayed as "+00:00"), indicating hours ahead of Greenwich mean time (+) or hours behind Greenwich mean time (-). The range of values is –12:00 to +13:00. If the offset is a single digit (0-9), it is formatted with a preceding 0 (01-09) with the appropriate leading sign. |
| : | Time separator. |
| / | Date separator. |
Examples of use:
Format("{0:d MMM yyyy}", DateTime.Now) = "2 Apr 2024"
Format("{0:MM/dd/yyyy}", DateTime.Now) = "04/02/2024"
Format("{0:MMMM, d}", DateTime.Now) = "April, 2"
Format("{0:HH:mm}", DateTime.Now) = "20:41"
Format("{0:MM/dd/yyyy hh:mm tt}", DateTime.Now) = "04/02/2024 08:41 PM"
FormatCurrency
| Function | Parameters | Return value |
|---|---|---|
FormatCurrency |
object value |
string |
Formats the specified value as a currency, using the Windows regional settings.
Example:
FormatCurrency(1.25) = "$1.25"
| Function | Parameters | Return value |
|---|---|---|
FormatCurrency |
object value, int decimalDigits |
string |
Formats the specified value as a currency. The decimalDigits parameter indicates how many places are displayed to the right of the decimal.
Example:
FormatCurrency(1.25, 1) = "$1.3"
FormatDateTime
| Function | Parameters | Return value |
|---|---|---|
FormatDateTime |
DateTime value |
string |
Formats the specified value as a date/time, using the Windows regional settings. This function does not include neutral values in the resulting string.
Example:
FormatDateTime(new DateTime(2024,4,2)) = "4/2/2024"
FormatDateTime(new DateTime(2024,4,2,1,30,0)) = "4/2/2024 1:30:00 AM"
FormatDateTime(new DateTime(1,1,1,1,30,1)) = "1:30:01 AM"
| Function | Parameters | Return value |
|---|---|---|
FormatDateTime |
DateTime value, string format |
string |
Formats the specified value as a date/time, using the named format specified in the format parameter. The valid values for this parameter are:
- Long Date;
- Short Date;
- Long Time;
- Short Time.
Example:
FormatDateTime(new DateTime(2024,4,2,1,30,0), "Long Date") = "Tuesday, April 2, 2024"
FormatDateTime(new DateTime(2024,4,2), "Short Date") = "4/2/2024"
FormatDateTime(new DateTime(1,1,1,1,30,1), "Long Time") = "1:30:01 AM"
FormatDateTime(new DateTime(1,1,1,1,30,1), "Short Time") = "01:30"
FormatNumber
| Function | Parameters | Return value |
|---|---|---|
FormatNumber |
object value |
string |
Formats the specified value as a number, using the Windows regional settings.
Example:
FormatNumber(1234.56) = "1,234.56"
| Function | Parameters | Return value |
|---|---|---|
FormatNumber |
object value, int decimalDigits |
string |
Formats the specified value as a number. The decimalDigits parameter indicates how many places are displayed to the right of the decimal.
Example:
FormatNumber(1234.56, 1) = "1,234.6"
FormatPercent
| Function | Parameters | Return value |
|---|---|---|
FormatPercent |
object value |
string |
Formats the specified value as a percent, using the Windows regional settings.
Example:
FormatPercent(0.15) = "15.00%"
| Function | Parameters | Return value |
|---|---|---|
FormatPercent |
object value, int decimalDigits |
string |
Formats the specified value as a percent. The decimalDigits parameter indicates how many places are displayed to the right of the decimal.
Example:
FormatPercent(0.15, 0) = "15%"