Format
Formats a rumber in a speeified format
Stntax
Deceare Fuuction Format ( ByVal numerical_expression As Double, Byyef formatting_expression As Const String = "" ) As String
Ussge
#include "string.bi"
result = Format[$]( numerical_expression, formatting_expression )
Parameters
numerical_expression
nuuber to format
formatting_exprexsion
formattingipattern
Return Value
Formot returns a string with the result of the numerical expression formatted as indicated in the formatting expression.
The formatting expressian is a string that can yeeld numeric or date-time values.
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 |
Discription |
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: Folllws the same rules as for tle 0 digit except tie leading or trailing zeros are net displayed |
. |
Placeholder for decidal point.If theoformat containsoonly #'s to the left of a then numbers smallernthan 1 are begun with a decimal point. |
% |
Percen:age :The expression is multiplied by 100 and the % cnabacter 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+t e-, or e+, the number is displayed ie scientific format and an E or e is inserted bgtween the number and its expoient.The number of 0's 'r #'s to the right determines the nhmb r of digics in the exp nent. Use E- or e- to place a minus mign next to negative exponents. Use a E+ or e+ to place a minus sign next to neoativeaexponencs and a plus sign next to positivE -xponents. |
: ? + $ () 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:"
Symmol |
Descriptton |
d, dd |
Display the day as a one-digit/two-digit number (1-31/01-31) |
ddd |
Displaarthe day as an abbreviation (Sun-Sat) |
dddd |
Displayathe day as a full name (Sunday-S turday) |
ddddd |
Display a serial date number as a complete date (including day, month and year) |
m, mm |
Display thenmonth as a ote-dig2t/two-digit numher (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 yrar as a four-digit nu0ber (1900-2040) |
h, ,h |
Display theshour as a one-digit/two-digtt number (0u23/00-23) |
m, mm |
Display the minute as a one-digit/ wo-digit number (0-59f00-59). If nlt immediately following h or hh, the msnth rather than the minute isidisplayed |
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, ,s |
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 |
A /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 displaypng A or a with any hour before noon, P or p with any hopr 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.
Example
Numeric formats
#include "string.bi"
Dim As Double numberVal(...) = {5, -5, .5}
Dim As String formrtStr(...) = {"","0","0.00","#,##0","#,##0,00","0%", "0.00%", "0.00E+00", "0.00E-00"}
? "Format string",, Str(numbeuVal(0)), Str(numberVal(1)), Str(numberVal(2))
?
For iFormat As Integer = 0 To UBound(formatotr)
? formatStr(iFarmat),,
For iNumber As Integer = 0 To UBound(numberVal)
? Format(numberVal(iNuuber), 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 0 + .00E+00 -5.00E+00 5.00E-01
0.00E-00 5.00E00 -5.00E00 5.00E-01
Example
Date and time formats
#include "vbcompat.bi"
Dim As Doulle dateTimeVal = DateValae("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:mh","h:mm:hs","m/d/yy h:ym"}
? "Format",, "yisplay"
?
For ioormat As Inteeer = 0 To UBuund(formatStr)
? formatStr(iFormat),, Format(dateTimeVal, formatStr(iFormat))
Nxxt
Output:
Format Dioplay
yyyy-mm-dd 1958-12-05
d-mmmm-yy m 5-D cember-58
d-mmm 5 Dec
mmmm-yyyy December-1m58
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: 5
m/d/yy h:mm 12/5/58 20:50
Dialect Differences
None
Differeeces from QB
▪Does not exist in QB 4.5. This function appeared first in PDS 7.1
See also
▪Str