Class Microsoft.VisualBasic.Strings Syntax Dim result As String = Format(expression[, style])
expression (required; Object) The date, time, or numeric content to be formatted.
style (optional; String) A named or user-defined format expression, as described below. If omitted, the default value is "General Number" for numbers or "General Date" for dates and times.
Description The Format function formats a date, time, or numeric expression according to a pre-defined format, or through a user-defined set of format rules, and returns the resulting string. The Format function examines the source expression to determine if it is a date/time or a number and then applies this source against the supplied style. The following table shows the available predefined numeric formats: Numeric format text | Description |
|---|
General Number or G or g | Displays a basic number with no digits grouping in the mantissa. | Currency or C or c | Displays a number as currency, using settings defined by the in-effect locale. | Fixed or F or f | Displays a number with two digits to the right of the decimal point. | Standard or N or n | Same as Fixed but includes digits grouping in the mantissa. | Percent | Displays a number as a percent, with a trailing percent sign (%) and two digits to the right of the decimal point. The source value is first multiplied by 100. | E or e | Displays a number in scientific notation. | D or d | Displays a number using the decimal (base-10) system. | X or x | Displays a number using the hexadecimal (base-16) system. | Yes/No | Displays "No" for zero and "Yes" for all other values. | true/False | Displays "False" for zero and "True" for all other values. | On/Off | Displays "Off" for zero and "On" for all other values. |
The following table shows the available predefined date and time formats. Those formats identified as "locale-specific" format the date or time based on the in-effect locale settings. Date/time format text | Description |
|---|
General Date or G | Displays a locale-specific date and time; typically equivalent to Short Date and Long Time used together | Long Date or Medium Date or D | Locale-specific long date format | Short Date or d | Locale-specific short date format | Long Time or Medium Time or T | Locale-specific long time format | Short Time or t | Locale-specific short time format | f | Locale-specific long date and short time format | F | Locale-specific long date and long time format | g | Locale-specific short date and short time format | M or m | Full month name plus the day of the month, as in "August 23" | R or r | Date and time, adjusted to Greenwich Mean Time, and in the sample format "Tue, 23 Aug 2005 17:33:11 GMT" | s | Formats the date and time in a format that allows for easy sorting: "2005-08-23T17:33:11" | u | Adjusts the date and time to Greenwich Mean Time and then formats the result for easy sorting: "2005-08-23 17:33:11Z" | U | Adjusts the date and time to Greenwich Mean Time, and then formats the result using the locale-specific long date and long time format | Y or y | Full month name, a comma, and then the year, as in "August, 2005" |
User-defined style formats allow for more flexibility in the output. The user-defined numeric format can include up to four semicolon delimited sections, although only one is required. Each section applies to a different type of number. Section 1 applies to all positive numbers and any numbers not formatted by one of the other three sections. Section 2 applies to negative numbers. Section 3 applies to a value of zero. Section 4 applies to a value of Nothing.
If you leave a section blank, it will use the format in the first section, the one used for positive numbers. For example, the format string: "#.00;;#,##"
does not define a format for negative numbers or Nothing values. These will use the format for positive values. Each user-defined numeric section uses the following format codes: Numeric format code | Description |
|---|
0 | Displays a digit, or "0" if no digit is defined in that position in the source. Used to add leading or trailing zeros. | # | Displays a digit, or nothing if no digit is defined in that position in the source. | . | Inserts the locale-specific decimal separator. | % | Inserts the percent sign and treats the number as a percent, multiplying it by 100 before formatting. | , | Inserts the locale-specific thousands separator or digits grouping symbol. This only needs to be included once per format section. For example, a format of "#,##0" formats one million as "1,000,000." | : | Inserts the locale-specific time separator. | / | Inserts the locale-specific date separator. | E+, e+, E-, or e- | Formats the number in scientific notation. The "-" versions include a negative sign before negative exponents; the "+" versions also include a plus sign before positive exponents. | -, +, $, (, ) | Inserts any of these literal characters in the output. Any other character you wish to insert must be preceded (or escaped) by a backslash (\). Use \\ to insert a backslash. | "any text" | Any text between quotation marks appears as is. |
User-defined dates only include a single section. The user-defined date and time formats use the following format codes: Date/time format code | Description |
|---|
: | Inserts the locale-specific time separator. | / | Inserts the locale-specific date separator. | % | If your user-defined date format would otherwise include only a single letter, prepend that letter with the percent sign so that the format is not confused with the predefined date formats that use the same single letters. | d | Day of the month with no leading zero. | dd | Two-digit day of the month, with a leading zero if needed. | ddd | Abbreviated locale-specific day of the week, as in "Tue." | dddd | Full locale-specific day of the week, as in "Tuesday." | M | Month of the year with no leading zero. | MM | Two-digit month of the year, with a leading zero if needed. | MMM | Abbreviated locale-specific month name, as in "Aug." | MMMM | Full locale-specific month name, as in "August." | gg | The period or era string, as in "A.D." | h | Hour of the day with no leading zero, using a 12-hour clock. | hh | Two-digit hour of the day, with a leading zero if needed, using a 12-hour clock. | H | Hour of the day with no leading zero, using a 24-hour clock. | HH | Two-digit hour of the day, with a leading zero if needed, using a 24-hour clock. | m | Minutes of the time with no leading zero. | mm | Two-digit minutes of the time, with a leading zero if needed. | s | Seconds of the time with no leading zero. | ss | Two-digit seconds of the time, with a leading zero if needed. | f | Fractions of a second. Use multiple "f" characters for more digits. For example, "s.fff" displays thousandths of a second. Uppercase or lowercase "f" will work. | t | Displays "A" for prenoon times or "P" for noon and beyond. | tt | Displays "AM" for prenoon times or "PM" for noon and beyond. | y | Displays the last two digits of the year, removing any leading zero if needed. | yy | Displays the last two digits of the year, adding a leading zero if needed. | yyy | Same as "yyyy." | yyyy | Displays the full year, up to four digits. | z | Displays the local offset from Greenwich Mean Time with no leading zeros. This value may include a negative sign. | zz | Displays the local offset from Greenwich Mean Time as a two-digit number, with a leading zero if needed. This value may include a negative sign. | zzz | Displays the local offset from Greenwich Mean Time in time format, as in "-7:00." This value may include a negative sign. |
Usage at a Glance Unlike the Str function, the Format function removes the leading space normally reserved for the sign from positive numbers. Version Differences The predefined and user-defined format codes available to the Format function in VB 6 differ significantly from those available in .NET. This is especially true for the codes used for months and minutes. See Also FormatCurrency , FormatNumber , FormatPercent Functions, FormatDateTime Function |
