Format

Home › String Functions › Format

Format

Formats a number with a picture string such as "#,##0.00".

Syntax

Declare Function Format ( ByVal numerical_expression As Double, ByRef formatting_expression As Const String = "" ) As String

Parameters

• numerical_expression
• formatting_expression

Description

To recover meaningful date-time values the numerical expression must be a date serial obtained from the appropriate functions.
This function is part of FreeBASIC, however it is not recognized by the compiler unless vbcompat.bi is included.

"Numeric Formats"

Symbol

Description

Null string

General format (no formatting)

0

Digit placeholder: If the number has fewer digits than there are zeros (on either side of the decimal) in the format expression, leading or trailing zeros are displayed. If there are more digits to the right of the decimal than zeros in the format, the number is rounded. If there are more digits to the left of the decimal than zeros in the format the digits are all displayed

Digit placeholder: Follows the same rules as for the 0 digit except the leading or trailing zeros are not displayed

.

Placeholder for decimal point.If the format contains only #'s to the left of . then numbers smaller than 1 are begun with a decimal point.

%

Percentage :The expression is multiplied by 100 and the % character is inserted.

,

Thousands separator. Two adjacent commas, or a comma immediately to the left of the decimal point location (whether there is a decimal specified or not) means 'Omit the three digits that fall between these commas, or between the comma and the decimal point, rounding as needed.'

E- E+ e- e+

Scientific format: If a format contains one digit placeholder (0 or #) to the right of an E-, E+, e-, or e+, the number is displayed in scientific format and an E or e is inserted between the number and its exponent.The number of 0's or #'s 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 a E+ or e+ to place a minus sign next to negative exponents and a plus sign next to positive exponents.

: ? + $ () space

Display literal character To display a character other than one of these, precede the character with a backslash (\) or enclose the character(s) in double quotation marks

\

Display next character in format string as it is

text between double quotes

Displays the text inside the double quotes.

:

Time separator is used to separate hours, minutes, and seconds when time values are formatted.

/

The date separator is used to separate day,month, and year when date values are formatted.

"Date-Time formats:"

Symbol	Description
d, dd	Display the day as a one-digit/two-digit number (1-31/01-31)
ddd	Display the day as an abbreviation (Sun-Sat)
dddd	Display the day as a full name (Sunday-Saturday)
ddddd	Display a serial date number as a complete date (including day, month and year)
m, mm	Display the month as a one-digit/two-digit number (1-12/01-12). If immediately following h or hh, the minute rather than the month is displayed
M, MM	Display the month as a one-digit/two-digit number (1-12/01-12), even if immediately following h or hh
mmm	Display the month as an abbreviation (Jan-Dec)
mmmm	Display the month as a full name (January-December)
y, yy	Display the year as a two-digit number (00-99)
yyyy	Display the year as a four-digit number (1900-2040)
h, hh	Display the hour as a one-digit/two-digit number (0-23/00-23)
m, mm	Display the minute as a one-digit/two-digit number (0-59/00-59). If not immediately following h or hh, the month rather than the minute is displayed
n, nn	Display the minute as a one-digit/two-digit number (0-59/00-59), even if not immediately following h or hh
s, ss	Display the second as a one-digit/two-digit number (0-59/00-59)
ttttt	Display a time serial number as a complete time, including hour, minute and second
AM/PM (Default), am/pm	Use the 12-hour clock displaying AM or am with any hour before noon, PM or pm with any hour between noon and 11:59
A/P, a/p	Use the 12-hour clock displaying A or a with any hour before noon, P or p with any hour between noon and 11:59

The representation of time and date separators may be determined from the operating system if regional or localized settings are supported by the target platform. This determination is made at run-time so that output may be localized to the system the program is running on.

Return Value

Format returns a string with the result of the numerical expression formatted as indicated in the formatting expression.
The formatting expression is a string that can yield numeric or date-time values.

Remarks

Usage

#include "string.bi"

result = Format[$]( numerical_expression, formatting_expression )

Dialect Differences

None

Differences from QB

• Does not exist in QB 4.5. This function appeared first in PDS 7.1

See also

• Print Using
• ? Using
• Str

Examples

Numeric formats

#include "string.bi"

Dim As Double numberVal(...) = {5, -5, .5}

Dim As String formatStr(...) = {"","0","0.00","#,##0","#,##0.00","0%", "0.00%", "0.00E+00", "0.00E-00"}

? "Format string",, Str(numberVal(0)), Str(numberVal(1)), Str(numberVal(2))

?

For iFormat As Integer = 0 To UBound(formatStr)

    ? formatStr(iFormat),,

    For iNumber As Integer = 0 To UBound(numberVal)

        ? Format(numberVal(iNumber), formatStr(iFormat)),

    Next

    ?

Next

Output:

Format string               5             -5            0.5

'                           5             -5            .5
0                           5             -5            0
0.00                        5.00          -5.00         0.50
#,##0                       5             -5            0
#,##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

Date and time formats

#include "vbcompat.bi"

Dim As Double dateTimeVal = DateValue("12/05/1958") + TimeValue("20:50:35")

Dim As String formatStr(...) = {"yyyy-mm-dd","d-mmmm-yy","d-mmm","mmmm-yyyy","h:mm AM/PM","h:mm:ss AM/PM","h:mm","h:mm:ss","m/d/yy h:mm"}

? "Format",, "Display"

?

For iFormat As Integer = 0 To UBound(formatStr)

    ? formatStr(iFormat),, Format(dateTimeVal, formatStr(iFormat))

Next

Output:

Format                      Display

yyyy-mm-dd                  1958-12-05
d-mmmm-yy                   5-December-58
d-mmm                       5-Dec
mmmm-yyyy                   December-1958
h:mm AM/PM                  8:50 PM
h:mm:ss AM/PM               8:50:35 PM
h:mm                        20:50
h:mm:ss                     20:50:35
m/d/yy h:mm                 12/5/58 20:50

---

Category: String Functions
Kind: function

---

Reproduced from the FreeBASIC Wiki Manual under the GNU Free Documentation License 1.3 — with no Invariant Sections, no Front-Cover Texts and no Back-Cover Texts. Copyright © the FreeBASIC project and wiki contributors. See License.