Formatting Numbers, Dates, and Strings
With the Format Function
The Format function returns a string containing an expression formatted according to instructions contained in a format expression. This function is useful for formatting numeric, date, time, and string data.
The Format function syntax has these parts:
|
Part |
Description |
|
Expression |
Required. Any valid expression. |
|
Style |
Optional. A valid named or user-defined format String expression. |
FORMATTING NUMBERS
Numbers can be formatted in many ways, using either Named (Pre-Defined) formats or Custom formats.
Formatting Numbers with Named (Pre-Defined) Formats
The Format function recognizes the following Named Numeric formats:
Named Numeric Format |
Description |
|
General Number (also "G" or "g") |
Displays the number as entered, with no rounding and no commas. |
|
Currency (also "C" or "c") |
Displays the number with a dollar sign, comma (if appropriate), and two digits to the right of the decimal point. Shows negative numbers inside parentheses. |
|
Fixed (also "F" or "f") |
Displays the number with at least one digit to the left of the decimal separator and two digits to the right. Does not show comma. |
|
Standard (also "N" or "n") |
Displays the number with at least one digit to the left of the decimal separator and two digits to the right and commas (if appropriate). |
|
Percent (also "P" or "p") |
Multiplies the value by 100 and displays the result with two digits to the right of the decimal point and a percent sign at the end. |
|
Scientific (also "E" or "e") |
Uses standard scientific notation. |
|
Yes/No |
Any nonzero numeric value is Yes. Zero is No. |
|
True/False |
Any nonzero numeric value is True. Zero is False. |
|
On/Off |
Any nonzero numeric value is On. Zero is Off. |
The above named numeric formats for the Format function were also available in earlier versions of VB. New in .NET are the single letter abbreviations for the first six items shown above. Two new formats in this category have been introduced in .NET:
|
"D" or "d" |
Displays number as a string that contains the value of the number in Decimal (base 10) format. This option is supported for integral types (Byte, Short, Integer, Long) only. |
|
"X" or "x" |
Displays number as a string that contains the value of the number in Hexadecimal (base 16) format. This option is supported for integral types (Byte, Short, Integer, Long) only. |
To demonstrate the named numeric formats described above, create a new "Try It" project, and place the following code in Sub Main:
Dim strUserInput As String
Dim dblTestNumber As Double
Console.Write("Please enter a number to demonstrate named numeric formats: ")
strUserInput = Console.ReadLine()
dblTestNumber = Val(strUserInput)
Console.WriteLine("Using General Number: " & Format(dblTestNumber, "General Number"))
Console.WriteLine("Using Currency: : " & Format(dblTestNumber, "Currency"))
Console.WriteLine("Using Fixed: " & Format(dblTestNumber, "Fixed"))
Console.WriteLine("Using Standard: " & Format(dblTestNumber, "Standard"))
Console.WriteLine("Using Percent: " & Format(dblTestNumber, "Percent"))
Console.WriteLine("Using Scientific: " & Format(dblTestNumber, "Scientific"))
Console.WriteLine("Using Yes/No: " & Format(dblTestNumber, "Yes/No"))
Console.WriteLine("Using True/False: " & Format(dblTestNumber, "True/False"))
Console.WriteLine("Using On/Off: " & Format(dblTestNumber, "On/Off"))
Console.WriteLine("Using D: " & Format(CInt(dblTestNumber), "D"))
Console.WriteLine("Using X: " & Format(CInt(dblTestNumber), "X"))
Console.ReadLine()
|
Run the project and enter 123456.789. The output will be displayed as shown in the screen shot on the right.
Test the code using a variety of different values, including negative numbers and zero.
|
|
Download the VB.NET project code for the example above here.
Formatting Numbers with Custom Formats
In addition to the named numeric formats described previously, you can also create custom numeric formats using a combination of specific characters recognized by the Format function. To format numbers, combinations of the following characters can be used:
|
Format Character |
Description |
|
0 Digit placeholder |
Display a digit or a zero. If the expression has a digit in the position where the 0 appears in the format string, display it; otherwise, display a zero in that position. If the number has fewer digits than there are zeros (on either side of the decimal) in the format expression, display leading or trailing zeros. If the number has more digits to the right of the decimal separator than there are zeros to the right of the decimal separator in the format expression, round the number to as many decimal places as there are zeros. If the number has more digits to the left of the decimal separator than there are zeros to the left of the decimal separator in the format expression, display the extra digits without modification. |
|
# Digit placeholder |
Display a digit or nothing. If the expression has a digit in the position where the # appears in the format string, display it; otherwise, display nothing in that position. This symbol works like the 0 digit placeholder, except that leading and trailing zeros aren't displayed if the number has the same or fewer digits than there are # characters on either side of the decimal separator in the format expression. |
|
. Decimal placeholder |
The decimal placeholder determines how many digits are displayed to the left and right of the decimal separator. If the format expression contains only number signs to the left of this symbol, numbers smaller than 1 begin with a decimal separator. If you always want a leading zero displayed with fractional numbers, use 0 as the first digit placeholder to the left of the decimal separator instead. (Note: In some locales, a comma is used as the decimal separator. The actual character used as a decimal placeholder in the formatted output depends on the Number Format recognized by your system.) |
|
% Percent placeholder |
The expression is multiplied by 100. The percent character (%) is inserted in the position where it appears in the format string. |
|
, (comma) Thousand separator |
The thousand separator separates thousands from hundreds within a number that has four or more places to the left of the decimal separator. Standard use of the thousand separator is specified if the format contains a thousand separator surrounded by digit placeholders (0 or #). Two adjacent thousand separators or a thousand separator immediately to the left of the decimal separator (whether or not a decimal is specified) means "scale the number by dividing it by 1000, rounding as needed." You can scale large numbers using this technique. For example, you can use the format string "##0,," to represent 100 million as 100. Numbers smaller than 1 million are displayed as 0. Two adjacent thousand separators in any position other than immediately to the left of the decimal separator are treated simply as specifying the use of a thousand separator. (Note: In some locales, a period is used as a thousand separator. The actual character used as the thousand separator in the formatted output depends on the Number Format recognized by your system.) |
|
- + $ ( )
space |
Displays the character as is, in the position specified by the format string. To display a character other than one of those listed, precede it with a backslash (\). |
|
E-, E+, e-, or e+ (Scientific format) |
If the format expression contains at least one digit placeholder (0 or #) to the right of E-, E+, e-, or e+, the number is displayed in scientific format and E or e is inserted between the number and its exponent. The number of digit placeholders to the right determines the number of digits in the exponent. Use E- or e- to place a minus sign next to negative exponents. Use E+ or e+ to place a minus sign next to negative exponents and a plus sign next to positive exponents. |
To demonstrate custom numeric formats using combinations of the characters listed above, create a new "Try It" project, and place the following code in Sub Main:
Dim strUserInput As String
Dim dblTestNumber As Double
Console.Write("Please enter a number to demonstrate custom numeric formats: ")
strUserInput = Console.ReadLine()
dblTestNumber = Val(strUserInput)
Console.WriteLine("Using '00000.00' : " & Format(dblTestNumber, "00000.00"))
Console.WriteLine("Using '#####.##' : " & Format(dblTestNumber, "#####.##"))
Console.WriteLine("Using '##,##0.00': " & Format(dblTestNumber, "##,##0.00"))
Console.WriteLine("Using '$##0.00' : " & Format(dblTestNumber, "$##0.00"))
Console.WriteLine("Using '0.00%' : " & Format(dblTestNumber, "0.00%"))
Console.ReadLine()
|
Run the project and enter 1234.5. The output will be displayed as shown in the screen shot on the right.
Test the code using a variety of different values, including negative numbers and zero.
|
|
Download the VB.NET project code for the example above here.
Formatting Numbers Using Conditional (Multi-Part) Formatting
A user-defined (custom) format expression can have from one to three sections separated by semicolons. (If the format argument contains one of the named formats, only one section is allowed.)
|
If you use |
The result is |
|
One section |
The format expression applies to all values. |
|
Two sections |
The first section applies to positive values and zeros, the second to negative values. |
|
Three sections |
The first section applies to positive values, the second to negative values, and the third to zeros. |
The following example has two sections: the first defines the format for positive values and zeros; the second section defines the format for negative values.
$#,##0;($#,##0)
If you include semicolons with nothing between them, the missing section is printed using the format of the positive value. For example, the following format displays positive and negative values using the format in the first section and displays "Zero" if the value is zero.
$#,##0;;\Z\e\r\o
The following table shows would be output, given the indicated format string and inputs of 5, -5, and.5, respectively.
|
Format String |
Positive 5 |
Negative 5 |
Decimal .5 |
|
Zero-length string |
5 |
-5 |
0.5 |
|
0 |
5 |
-5 |
1 |
|
0.00 |
5.00 |
-5.00 |
0.50 |
|
#,##0 |
5 |
-5 |
1 |
|
$#,##0;($#,##0) |
$5 |
($5) |
$1 |
|
$#,##0.00;($#,##0.00) |
$5.00 |
($5.00) |
$0.50 |
|
0% |
500% |
-500% |
50% |
|
0.00% |
500.00% |
-500.00% |
50.00% |
|
0.00E+00 |
5.00E+00 |
-5.00E+00 |
5.00E-01 |
|
0.00E-00 |
5.00E00 |
-5.00E00 |
5.00E-01 |
Multiple format can be specified in the Console.WriteLine method also. The rules remain the same.
To demonstrate multiple formats using format function and Console.WriteLine method, set up another "Try It" project, and place the following code in the main method (note: this test only uses the first three sections of the multi-format string; Null values will not be tested for):
Dim strUserInput As String
Dim dblTestNumber As Double
Console.Write("Please enter a number to demonstrate multiple formats: ")
strUserInput = Console.ReadLine()
dblTestNumber = Val(strUserInput)
Console.WriteLine()
Console.WriteLine("Demo using the multi-format string '###,##0.00;(###,##0.00);\Z\E\R\O'")
Console.WriteLine()
Console.WriteLine("Your input was: " & CStr(dblTestNumber))
Console.WriteLine("The output is : " & Format(dblTestNumber, "###,##0.00;(###,##0.00); \Z\E\R\O"))
Console.ReadLine()
|
Run the project and enter 12345. The output will be displayed as shown in the screen shot on the right.
Test the code using a variety of different values, including negative numbers and zero.
|
|
Download the VB.NET project code for the example above here
FORMATTING DATES
Like numbers, dates can be formatted in many ways, using either Named (Pre-Defined) formats or Custom formats
Formatting Dates with Named (Pre-Defined) Formats
The Format function recognizes the following Named Date/Time formats:
|
Named Date/Time Format |
Description |
|
General Date (also "G") |
Shows date and time if expression contains both. If expression is only a date or a time, the missing information is not displayed. |
|
Long Date (also "D") |
Uses the Long Date format specified in the Regional Settings dialog box of the Microsoft Windows Control Panel. |
|
Medium Date |
Uses the dd-mmm-yy format (for example, 03-Apr-93) |
|
Short Date (also "d") |
Uses the Short Date format specified in the Regional Settings dialog box of the Windows Control Panel. |
|
Long Time (also "T") |
Shows the hour, minute, second, and "AM" or "PM" using the h:mm:ss format. |
|
Medium Time |
Shows the hour, minute, and "AM" or "PM" using the "hh:mm AM/PM" format. |
|
Short Time (also "t") |
Shows the hour and minute using the hh:mm format. |
The above named date/time formats for the Format function were also available in earlier versions of VB. New in .NET are the single letter abbreviations for some of the items shown above.
|
"f" |
Displays the long date and short time according to your locale's format. |
|
"F" |
Displays the long date and long time according to your locale's format. |
|
"g" |
Displays the short date and short time according to your locale's format. |
|
"M" or "m" |
Displays the month and the day of a date. |
|
"R" or "r" |
Formats the date and time as Greenwich Mean Time (GMT) |
|
"s" |
Formats the date and time as a sortable index. |
|
"u" |
Formats the date and time as a GMT sortable index. |
|
"U" |
Formats the date and time with the long date and long time as GMT. |
|
"y" |
Formats the date as the year and month. |
This next example uses the Now keyword. There are three VB keywords related to the current date and/or time:
Now Returns the current date and time
Today Returns the current date (formerly Date in previous versions of VB)
TimeOfDay Returns the current time (formerly Time in previous versions of VB)
To demonstrate the named date and time formats described above, create a new "Try It" project, and place the following code in Sub Main:
Console.WriteLine()
Console.WriteLine("Using General Date: " & Format(Now, "General Date"))
Console.WriteLine("Using Long Date: " & Format(Now, "Long Date"))
Console.WriteLine("Using Medium Date: " & Format(Now, "Medium Date"))
Console.WriteLine("Using Short Date: " & Format(Now, "Short Date"))
Console.WriteLine("Using Long Time: " & Format(Now, "Long Time"))
Console.WriteLine("Using Medium Time: " & Format(Now, "Medium Time"))
Console.WriteLine("Using Short Time: " & Format(Now, "Short Time"))
Console.WriteLine()
Console.WriteLine("Using f: " & Format(Now, "f"))
Console.WriteLine("Using F: " & Format(Now, "F"))
Console.WriteLine("Using g: " & Format(Now, "g"))
Console.WriteLine("Using M: " & Format(Now, "M"))
Console.WriteLine("Using R: " & Format(Now, "R"))
Console.WriteLine("Using s: " & Format(Now, "s"))
Console.WriteLine("Using u: " & Format(Now, "u"))
Console.WriteLine("Using U: " & Format(Now, "U"))
Console.WriteLine("Using y: " & Format(Now, "y"))
Console.ReadLine()
|
Run the project. The current date and/or time, formatted in the various ways, will be displayed: |
|
Download the VB.NET project code for the example above here.
Formatting Dates with Custom Formats
In addition to the named date/time formats described previously, you can also create custom date/time formats using a combination of specific characters recognized by the Format function, shown in the table below:
|
Character |
Description |
|
(:) |
Time separator. In some locales, other characters may be used to represent the time separator. The time separator separates hours, minutes, and seconds when time values are formatted. The actual character used as the time separator in formatted output is determined by your system's LocaleID value. |
|
(/) |
Date separator. In some locales, other characters may be used to represent the date separator. The date separator separates the day, month, and year when date values are formatted. The actual character used as the date separator in formatted output is determined by your locale. |
|
(%) |
Used to indicate that the following character should be read as a single-letter format without regard to any trailing letters. Also used to indicate that a single-letter format is read as a user-defined format.
The need for this is because certain single-letter format specifiers are used as pre-defined formats. For example, the format specifier "d" is used for the pre-defined "Short Date" format; however, as indicated below, the letter "d" is also used to specify the day as a number when used in a user-defined format. So if you wanted to make a user-defined format that displays only the day number, there would be a conflict. The use of the % character resolves that conflict.
For example, on August 29, 2005, Format(Now, "d") would return 8/29/2005 Format(Now, "%d") would return 29 |
|
d |
Displays
the day as a number without a leading zero (for example, |
|
dd |
Displays
the day as a number with a leading zero (for example, |
|
ddd |
Displays
the day as an abbreviation (for example, |
|
dddd |
Displays
the day as a full name (for example, |
|
M |
Displays
the month as a number without a leading zero (for example, January is
represented as |
|
MM |
Displays
the month as a number with a leading zero (for example, |
|
MMM |
Displays
the month as an abbreviation (for example, |
|
MMMM |
Displays
the month as a full month name (for example, |
|
gg |
Displays
the period/era string (for example, |
|
h |
Displays
the hour as a number without leading zeros using the 12-hour clock (for
example, |
|
hh |
Displays
the hour as a number with leading zeros using the 12-hour clock (for example,
|
|
H |
Displays
the hour as a number without leading zeros using the 24-hour clock (for
example, |
|
HH |
Displays
the hour as a number with leading zeros using the 24-hour clock (for example,
|
|
m |
Displays
the minute as a number without leading zeros (for example, |
|
mm |
Displays
the minute as a number with leading zeros (for example, |
|
s |
Displays
the second as a number without leading zeros (for example, |
|
ss |
Displays
the second as a number with leading zeros (for example, |
|
f |
Displays fractions of seconds. For example ff will display hundreths of seconds, whereas ffff will display ten-thousandths of seconds. You may use up to seven f symbols in your user-defined format. Use %f if this is the only character in your user-defined numeric format. |
|
t |
Uses the
12-hour clock and displays an uppercase |
|
tt |
Uses the
12-hour clock and displays an uppercase |
|
y |
Displays the year number (0-9) without leading zeros. Use %y if this is the only character in your user-defined numeric format. |
|
yy |
Displays the year in two-digit numeric format with a leading zero, if applicable. |
|
yyy |
Displays the year in four digit numeric format. |
|
yyyy |
Displays the year in four digit numeric format. |
|
z |
Displays
the timezone offset without a leading zero (for example, |
|
zz |
Displays
the timezone offset with a leading zero (for example, |
To demonstrate custom numeric formats using combinations of the characters listed above, create a new "Try It" project, and place the following code in Sub Main:
Console.WriteLine("Using 'M/d/yy': " & Format(Now, "M/d/yy"))
Console.WriteLine("Using 'MM/dd/yyyy': " & Format(Now, "MM/dd/yyyy"))
Console.WriteLine("Using 'yyyy-MM-dd': " & Format(Now, "yyyy-MM-dd"))
Console.WriteLine("Using 'dddd, MMMM dd, yyyy': " & Format(Now, "dddd, MMMM dd, yyyy"))
Console.WriteLine("Using 'dddd, MMMM dd, yyyy gg': " & Format(Now, "dddd, MMMM dd, yyyy gg"))
Console.WriteLine("Using 'd-MMM': " & Format(Now, "d-MMM"))
Console.WriteLine("Using 'MMMM-yy': " & Format(Now, "MMMM-yy"))
Console.WriteLine("Using 'hh:mm tt': " & Format(Now, "hh:mm tt"))
Console.WriteLine("Using 'h:mm:ss t': " & Format(Now, "h:mm:ss t"))
Console.WriteLine("Using 'd-MMMM h:mm': " & Format(Now, "d-MMMM h:mm"))
Console.WriteLine("Using 'd-MMMM-yy': " & Format(Now, "d-MMMM-yy"))
Console.WriteLine("Using 'd MMMM': " & Format(Now, "d MMMM"))
Console.WriteLine("Using 'MMMM yy': " & Format(Now, "MMMM yy"))
Console.WriteLine("Using 'h:mm': " & Format(Now, "h:mm"))
Console.WriteLine("Using 'h:mm:ss': " & Format(Now, "h:mm:ss"))
Console.WriteLine("Using 'H:mm:ss': " & Format(Now, "H:mm:ss"))
Console.WriteLine("Using 'HH:mm:ss zzz': " & Format(Now, "HH:mm:ss zzz"))
Console.WriteLine("Using 'M/d/yy h:mm': " & Format(Now, "M/d/yy h:mm"))
Console.WriteLine("Using 'M/d/yy h:mm tt': " & Format(Now, "M/d/yy h:mm tt"))
Console.WriteLine("Using 'MM/dd/yy HH:mm': " & Format(Now, "MM/dd/yy HH:mm"))
Console.ReadLine()
|
Run the project. The current date and/or time, formatted in the various ways, will be displayed: |
|
Download the VB.NET project code for the example above here.
Summary of Date/Time Format Function Changes (VB6 vs. VB.NET)
|
VB6 |
VB.NET |
|
"ddddd" and "dddddd" could be used to display the short date or long date, respectively. |
Not supported; both behave the same as "dddd" to display the full name of the day. To display the short date use the pre-defined format "Short Date" or "d"; for the long date use the pre-defined format "Long Date" or "D". |
|
"w" could be used to display the day of week (1 through 7) |
Not supported as a Format specifier. Instead, the DatePart function can be used as follows:CStr(DatePart("w", DateTimeVariable))- or -CStr(DatePart(DateInterval.Weekday, DateTimeVariable)) |
|
"ww" could be used to display the week of year (1 through 53) |
Not supported as a Format specifier. Instead, the DatePart function can be used as follows:CStr(DatePart("ww", DateTimeVariable))- or -CStr(DatePart(DateInterval.WeekOfYear, DateTimeVariable)) |
|
"q" could be used to display the quarter of the year as a number from 1 to 4 |
Not supported as a Format specifier. Instead, the DatePart function can be used as follows:CStr(DatePart("q", DateTimeVariable))- or -CStr(DatePart(DateInterval.Quarter, DateTimeVariable)) |
|
Uppercase "M" or lowercase "m" could be used to display either the month or minute ("M" or "m" would be interpreted as the minute if it immediately followed "H" or "h"). Also, uppercase "N" or lowercase "n" could be used to display the minute. |
"M" is now case-sensitive. Uppercase "M" is used for the month; lowercase "m" is used for the minute. "N" and "n" are not used. |
|
Uppercase "H" or lowercase "h" could be used display the hour. If one of the "AM/PM" specifiers was also used, the hour would be a value between 1 and 12; otherwise, the hour would be a value between 0 and 23. |
"H" is now case-sensitive. Uppercase "H" represents the hour on the 24-hour clock; lowercase "h" represents the hour on the 12-hour clock. |
|
Various AM/PM specifiers, such as "AM/PM", "am/pm", "A/P", "a/p", or "AMPM." could be used to display AM or PM (or just A or P) in upper or lower case. |
"t" is used to display "A" or "P"; "tt" is used to display "AM" or "PM". |
FORMATTING STRINGS
In classic VB (VB6), the Format function provided options for applying custom formatting to strings, such as converting the case, padding, and justification. In VB.NET, these options were dropped from the Format function, probably because the options provided are better handled through standard string-handling functions. However – if you really want to – you can resurrect this functionality through the Visual Basic Compatibility library. How to do this will be shown in the steps below.
First, let's take a look at the options that were provided. Custom string formatting could be accomplished by using the specific characters shown in the table below:
|
< Force lowercase |
Display all characters in lowercase format. |
|
> Force uppercase |
Display all characters in uppercase format. |
|
@ Character placeholder |
Display a character or a space. If the string has a character in the position where the @ appears in the format string, display it; otherwise, display a space in that position. Placeholders are filled from right to left unless there is an ! character in the format string. |
|
& Character placeholder |
Display a character or nothing. If the string has a character in the position where the & appears, display it; otherwise, display nothing. Placeholders are filled from right to left unless there is an ! character in the format string. |
|
! Force left to right fill of placeholders |
The default is to fill from right to left. |
|
\ (Display the next character in the format string) |
Many characters in the format expression have a special meaning and can't be displayed as literal characters unless they are preceded by a backslash. The backslash itself isn't displayed. Using a backslash is the same as enclosing the next character in double quotation marks. To display a backslash, use two backslashes (\\). Examples of characters that can't be displayed as literal characters are the date- and time-formatting characters (a, c, d, h, m, n, p, q, s, t, w, y, and /:), the numeric-formatting characters (#, 0, %, E, e, comma, and period), and the string-formatting characters (@, &, <, >, and !). |
|
"ABC" (Display the string inside the double quotation marks) |
To include a string in format from within code, you must enclose the text in quotation marks (to embed a quotation mark within a quoted string, use to consecutive quotation marks for the embedded quotation mark). |
To demonstrate custom string formats using combinations of the characters listed above, create a new "Try It" project. But before you can add the code, you must first prepare the program to use the legacy version of the Format function. How to do this is shown in the steps below:
|
Select Add Reference from the IDE Project menu: |
|
|
From the Add Reference dialog screen, select Microsoft.VisualBasic.Compatibility: |
|
|
Add the line Imports Microsoft.VisualBasic.Compatibility.VB6 as the first line of the module:
|
|
At this point, you can add the code. Place the following code in Sub Main. (Note that you must qualify the Format function with Support.).
Dim strName As String
Console.Write("Please enter your name: ")
strName = Console.ReadLine()
Console.WriteLine()
Console.WriteLine("Using '>': " & Support.Format(strName, ">"))
Console.WriteLine("Using '<': " & Support.Format(strName, "<"))
Console.WriteLine("Using '@': " & "Hello there, " & Support.Format(strName, "@@@@@@@@@@") & ". How are you?")
Console.WriteLine("Using '&': " & "Hello there, " & Support.Format(strName, "&&&&&&&&&&") & ". How are you?")
Console.WriteLine("Using '!@': " & "Hello there, " & Support.Format(strName, "!@@@@@@@@@@") & ". How are you?")
Console.WriteLine("Using '!&': " & "Hello there, " & Support.Format(strName, "!&&&&&&&&&&") & ". How are you?")
Console.WriteLine("Using '\': " & Support.Format(strName, "\H\e\l\l\o\,\ &&&&&&&&&&\."))
Console.WriteLine("Using embedded quotes: " & Support.Format(strName, """Hello, ""&&&&&&&&&&""."""))
Console.ReadLine()
|
Run the project. Enter your name when prompted, and note the effects of the formatting options used. |
|
Download the VB.NET project code for the example above here.