Formatting values

There are many ways to control the display and formatting of numbers, dates, and times.

Numbers

Numbers are stored unformatted. Fortunately, all of the numeric data types (Double, Currency, Integer and Single) include a ToString function that can convert them to a formatting string value. The ToString function of Double, Integer and Single all take a format specification (see below). Currency does not. It respects the user's locale and system settings regarding currency formatting.

For example, this code converts a double to a string formatting for US dollars then assigns it to a label:

Var money As Double = 34.56
Label1.Text = money.ToString("$###.00")

An alternative to ToString is the Format function makes providing formatting to numbers easy. The resulting number is formatted to use the number formatting of your OS settings. To use this function, pass it a format specification and the number you wish formatted. The Format function then returns a string that represents the number with the formatting applied to it. The syntax for the Format function is:

result = Format(Number, FormatSpec)

Another alternative is the Str function works similarly to Format, but it does not use the OS settings to format the number.

result = Str(Number, FormatSpec)

For example, the decimal “.” is always used as the decimal separator when Str is used to format the number regardless of what the OS number format setting specifies. Use the Format function for numbers that should be displayed to the user. Use Str function for numbers that should be stored (perhaps in a database or XML file).

FormatSpec

The FormatSpec is a string made up of one or more characters that control how the number will be formatted. For example, the format spec “$###,##0.00” applies the dollars and cents formatting used in the United States.

On Windows, the character that is used as the Decimal and Thousands separator is specified by the user in the Regional Settings Control Panel. On Mac, these characters are specified on the Formats panel of the International system preference.

By default, the FormatSpec applies to all numbers. If you want to specify different FormatSpecs for positive numbers, negative numbers, and zero, simply separate the formats with semi-colons within the FormatSpec. The order in which you supply FormatSpecs is: positive, negative, zero. These characters are used in a FormatSpec:

Format Character

Description

#

Placeholder that displays the digit from the value if it's present.

0

Placeholder that displays the digit from the value if it's present. If no digit is present, 0 (zero) is displayed in its place.

.

Placeholder for the position of the decimal character.

,

Placeholder that indicates that the number should be formatted with thousands separators.

%

Displays the number multiplied by 100 (or as a percent).

(

Displays an open parenthesis.

)

Displays a closing parenthesis.

Displays a plus sign to the left of the number if the number is positive or a minus sign if the number is negative.

Displays a minus sign to the left of the number if the number is negative. Nothing is displayed for positive numbers.

E or e

Displays the number in scientific notation.

\

Displays the character that follows the backslash. Use this to display other characters in the output.

Here are some example FormatSpecs and their corresponding output (on a US-based system):

Format Syntax

Output

Format(1.784, #.##)

1.78

Format(1.3, #.0000)

1.3000

Format(5, 0000)

0005

Format(0.25, #%)

25%

Format(145678.5, ###,###.##)

145,678.5

Format(145678.5, #.##e+)

1.46E+05

Format(-3.7, -#.##)"-3.7

Format(3.7, +#.##)

+3.7

Format(3.7, #.##; (#.##); \z\e\r\o)

3.7

Format(0, #.##; (#.##); \z\e\r\o)

zero

Dates

Dates are stored using as objects via the DateTime class and have properties that hold the date in various different formats. To get a date as a string formatted in a specific way, you simply access the appropriate property.

Property

Default Output (on US-based systems)

Full

Tuesday, September 1, 2020

Long

September 1, 2020

Medium

Sep 1, 2020

Short

9/1/20

None

Date formats are controlled by the user's Date Properties (Windows) or Date Formats (Mac) system settings. On Mac, the Date Formats dialog is accessed from the Formats panel of the “Languages & Text” system preference (Click Customize... in the Date area in the Formats panel). On Windows, Date Properties is a screen in the Regional Options control panel. Users can choose the order of the day, month, year, as well as the separators.

The DateTime.FormatStyles use whatever format that the user has set in these system settings and may not match what is in the table.

To get the current date in any of these formats, simply create and instantiate a DateTime object and then call the ToString method and pass it the format style in which you want the DateTime. In this example, the current date formatted as a long date, is assigned to a variable:

Var now As DateTime = DateTime.Now
Var theDate As String
theDate = now.FormatStyles.Long

The DateTime.SecondsFrom1970 property is the “master” property that stores the date/time associated with the object.

Times

Like dates, time values are stored as part of a DateTime. Time values have five different formats:

Property

Default Output (on US-based systems)

Full

3:09:52 PM Central Daylight Time

Long

3:09:52 PM CDT

Medium

3:09:52 PM

Short

3:09 PM

None

As is the case with date formats, several aspects of these formats are controlled by the user via the Time screen in the Regional Settings Control panel on Windows or the Time Formats panel in “Languages & Text” preferences (Mac).