Format

Format formats a numeric value and returns it as a string.

Syntax

Format(strFlag, numValue, optStrDecimalMark, optStrThousandSep)

strFlag

A description of how the given numeric value should be formatted, according to the syntax %length.precisionFormat, where:

length is the minimum number of characters to be returned by the function — that is, the minimum length of the resulting string. If the value to be returned is shorter than this, it is padded with either blank spaces (" ") or zeroes ("0"); see the examples below. The value is not truncated even if the result is longer than the specified length. Applicable for Format values d, x, X, o, b, f, e, E, g, G, s, c, and h.

precision is the number of decimal places for a floating-point number. Applicable for Format values f, e, E, g, and G.

Format is the specific format:

Alternatively, the format can be set using the syntax ##.###, where the numeric value is rounded to the specified number of decimal places.

numValue

The numeric value argument on which the function operation will be performed.

optStrDecimalMark

The character used as the decimal mark, which separates the integer and fractional parts of the numeric value. This is an optional parameter; the default is a period (.). For example: "123.45"

optStrThousandSep

The character used as the thousands separator, which separates the hundreds and thousands digits of the numeric value. This is an optional parameter; the default character is a comma (,).

Return value

This function returns a string that contains the formatted numeric value. See the examples below.

Notes

Format is similar to the printf function in other programming languages, and it allows most of the same formatting options. However, unlike printf, Format can be used to format only one numeric value at a time.

This function is particularly useful for formatting values to be printed in reports.

When you use this function to format a numeric value using scientific notation (when you specify e, E, g, or G for the Format part of strFlag), the return value will be somewhat different depending on the runtime edition of the project.

• If project is run on Windows or Windows Embedded, the return value will show three characters for the exponent (for example, 1.2e+001).

• If the project is run on IoT View, the return value will show only two characters for the exponent (for example, 1.2e+01).

This behavior is determined by the operating system and cannot be changed anywhere in the project. The actual numeric values are the same, but the difference in the number of characters means the resulting strings are different, especially if you also use the length part of strFlag to determine the minimum length of the strings. Also, because the resulting strings are different, they might be handled differently by other functions that are subsequently executed.

Examples

Note: The examples above of scientific notation (e, E, g, G) are valid only for projects running on Windows and Windows Embedded. Projects running on IoT View will return values with only two characters for the exponent. For more information, see Notes above.