Purpose
Returns a string representing a custom-formatted number. You can call this function from the MapBasic window in MapInfo Pro.
Syntax
Format$ ( value, pattern ) value is a numeric expression.
pattern is a string which specifies how to format the results.
Return Value
String
Description
The Format$() function returns a string representing a formatted number. Given a numeric value such as 12345.67, Format$() can produce formatted results such as "$12,345.67".
The value parameter specifies the numeric value that you want to format.
The pattern parameter is a string of code characters, chosen to produce a particular type of formatting. The pattern string should include one or more special format characters, such as #, 0, %, the comma character (,), the period (.), or the semi-colon (;); these characters control how the results will look. The table below summarizes the format characters.
| pattern character | Role in formatting results: |
|---|---|
|
The result will include one or more digits from the value. |
| If the pattern string contains one or more # characters to the left of the decimal place, and if the value is between zero and one, the formatted result string will not include a zero before the decimal place. | |
|
A digit placeholder similar to the # character. If the pattern string contains one or more 0 characters to the left of the decimal place, and the value is between zero and one, the formatted result string will include a zero before the decimal place. See examples below. |
|
The pattern string must include a period if you want the result string to include a "decimal separator." The result string will include the decimal separator currently in use on the user's computer. To force the decimal separator to be a period, use the Set Format statement. |
|
The pattern string must include a comma if you want the result string to include "thousand separators." The result string will include the thousand separator currently set up on the user's computer. To force the thousand separator to be a comma, use the Set Format statement. |
|
The result will represent the value multiplied by one hundred; thus, a value of 0.75 will produce a result string of "75%". If you wish to include a percent sign in your result, but you do not want MapBasic to multiply the value by one hundred, place a \ (back slash) character before the percent sign (see below). |
|
The result is formatted with scientific notation. For example, the value 1234 produces the result "1.234e+03". If the exponent is positive, a plus sign appears after the "e". If the exponent is negative (which is the case for fractional numbers), the results include a minus sign after the "e". |
|
This string of control characters functions just as the "E+" string, except that the result will never show a plus sign following the "e". |
|
By including a semicolon in your pattern string, you can specify one format for positive numbers and another format for negative numbers. Place the semicolon after the first set of format characters, and before the second set of format characters. The second set of format characters applies to negative numbers. If you want negative numbers to appear with a minus sign, include "-" in the second set of format characters. |
|
If the back slash character appears in a pattern string, MapBasic does not perform any special processing for the character which follows the back slash. This lets you include special characters (for example, %) in the results, without causing the special formatting actions described above. |
Error Conditions
ERR_FCN_INVALID_FMT (643) error generated if the pattern string is invalid.
Examples
The following examples show the results you can obtain by using various pattern strings. The results are shown as comments in the code.
Format$( 12345, ",#") ' returns "12,345"
Format$(-12345, ",#") ' returns "-12,345"
Format$( 12345, "$#") ' returns "$12345"
Format$(-12345, "$#") ' returns "-$12345"
Format$( 12345.678, "$,#.##") ' returns "$12,345.68"
Format$(-12345.678, "$,#.##") ' returns "-$12,345.68"
Format$( 12345.678, "$,#.##;($,#.##)") 'returns "$12,345.68"
Format$(-12345.678, "$,#.##;($,#.##)") 'returns "($12,345.68)"
Format$(12345.6789, ",#.###") ' returns "12,345.679"
Format$(12345.6789, ",#.#") ' returns "12,345.7"
Format$(-12345.6789, "#.###E+00") ' returns "-1.235e+04"
Format$( 0.054321, "#.###E+00") ' returns "5.432e-02"
Format$(-12345.6789, "#.###E-00") ' returns "-1.235e04"
Format$( 0.054321, "#.###E-00") ' returns "5.432e-02"
Format$(0.054321, "#.##%") ' returns "5.43%"
Format$(0.054321, "#.##\%") ' returns ".05%"
Format$(0.054321, "0.##\%") ' returns "0.05%"See Also:
Str$() function