Home > Language Reference > Functions > Strings

Format Function

Returns a string containing a numeric expression or a date formatted according to the instructions contained in a formatting expression.

Syntax

Public Function Format(ByVal vValue As Double, ByRef sFormat As String, Optional ByVal bLocale As Boolean = True) As String
Public Function Format(ByVal vValue As Date, ByRef sFormat As String, Optional ByVal bLocale As Boolean = True) As String

Remarks

The Format function only handles numbers and dates. This function cannot format other types of data. If the vValue parameter does is not a Byte, Integer, Long, Single, Double or Date, a compile time error will occur.

The sFormat parameter defines the format of the string returned. It can contain either a predefined format name or a user defined format. The syntax of this parameter is explained later on. If you use a date format to format a number, or if you use a number format to format a date, a runtime error will occur.

The optional bLocale parameter indicates if the function should take into account the local settings when formatting. If the parameter is False, the numbers are formatted without thousands separators, and the decimal separators will be decimal point. Dates will be formated using the '/' character as a date separator, and the ':' character as the hour separator. If this parameter is True, the separators used are those defined in the system preferences.

Named numeric formats

The following table identifies the predefined numeric format names:

For example, on a device configured to use US number formats :

Format(12345.987,"currency")   ' Returns "12,346.99"
Format(12345.987,"integer")    ' Returns "12,346"
Format(12345.987,"scientific") ' Returns "1.235E4"
Format(12345.987,"engineer")   ' Returns "12.346E3"

User defined numeric formats

A user defined number format should use the following syntax::

[ + ] num [ . num ] [ { e | E | g | G } [ + ] num ]

The table below explain the meaning of the different elements :

The num format specifier is made up of a number of zero's or '#' indicating the number of characters to display, for example "00" ou "###". The zero character indicates a compulsory digit, whilst the # character indicates an optional digit.

For example, on a device configured to use US number formats :

Format(12345.987,"0.0")      ' Returns "12,346.0"
Format(12345.987,"0.00")     ' Returns "12,345.99"
Format(12345.987,"0.0000")   ' Returns "12,345.9870"
Format(12345.987,"0.####")   ' Returns "12,345.987"
Format(12345.987,"+000000")  ' Returns "+012,346"
Format(12345.987,"#.##E+00") ' Returns "1.23E+04"
Format(12345.987,"#.##g+0")  ' Returns "12.35e+3"

Named Date / Time formats

The following table identifies the predefined date and time format names:

For example, on a device configured to use US number formats :

Format(Now,"shortdate") ' Returns "12/31/99"
Format(Now,"longdate")  ' Returns "Dec 31 1999"
Format(Now,"iso")       ' Returns "1999-12-31T21:45:03"

User defined Date / Time formats

The format string can contain one or more of the following elements, in any order :

For example, on a device configured to use US number formats :

Format(Now,"hh:nn:ss")       ' Returns "23:59:59"
Format(Now,"hh:nn:ss am/pm") ' Returns "11:59:59 pm"
Format(Now,"mmmm dd yyyy")   ' Returns "December 31 1999"
Format(Now,"mm/dd/yyyy")     ' Returns "12/31/1999"

The Format function comes with 2 flavors, one for each data type it can handle. The compiler determines at compile time which version to call depending on the type of vValue. For more information about this mechanism, please refer to the Polymorphic functions topic.

System requirements