Start » Filter Reference » Basic » String » FormatRealToString

FormatRealToString

Basic

Module: FoundationLite

Creates a string from a real number using a proper format.

Applications

Useful for preparing a number for display or communication with specific number of fractional digits, sign etc.
Name Type Range Description
Input value
 inReal Real Input real
Input value
 inIntegerDigitCount Integer 0 - 1000 How many characters the integer part of the input real should have at least
Input value
 inFractionalDigitCount Integer 0 - 100 How many characters the fractional part of the input real should have
Input value
 inDecimalMark String The symbol used to separate the integer part from the fractional part of the number
Input value
 inTrailingCharacter String Defines the trailing character
Input value
 inForceSignPrinting Bool Forces printing the sign of the number even if the number is positive
Input value
 inSuffix String Defines a suffix. Generally it is an unit of value (e.g. mm)
Output value
 outString String Output string

Examples
inReal = 3.14159265359
inIntegerDigitCount = 2
inFractionalDigitCount = 3
inDecimalMark = "."
inTrailingCharacter = "0"
inForceSignPrinting = False
inSuffix = "..." 		outString = "03.142..."

In the example above desired integer digit count defined in inIntegerDigitCount equals 2, so the filter attaches trailing sign (zero) at the beginning of the result outString. Decimal mark (inDecimalMark) is set as a dot and the number of fractional digits (inFractionalDigitCount) as 3. The result string ends with ellipsis defined in inSuffix and the final result is "03.142...".
Note that the third digit was rounded up to "2" due to the succeeding digit.
inReal = 10.7
inIntegerDigitCount = 1
inFractionalDigitCount = 2
inDecimalMark = ","
inTrailingCharacter = " "
inForceSignPrinting = True
inSuffix = " °C" 		outString = "+10,70 °C"

This example demonstrates formatting of value 10.7 with one integer digit as defined in inIntegerDigitCount and two fractional digits described by inFractionalDigitCount. Note that the integer part of formatted number (1) is less than digits in integral part of passed value (10), but it doesn't affect to either (unlike the fractional part which can cuts off excessing digits).
Trailing character (inTrailingCharacter) doesn't affect to anything, because desired integer digit count is one (the same effect would be for zero).

Remarks

If you want to cut off excessing digits from a fractional part of a number (instead of rounding them), you can format a number with one extra precision digit and then use Substring to cut off the last digit. You can add a suffix manually by using ConcatenateStrings.

Errors

This filter can throw an exception to report error. Read how to deal with errors in Error Handling.

List of possible exceptions:

Error type Description
DomainError inDecimalMark has to be a single character in FormatRealToString.
DomainError inTrailingCharacter has to be a single character in FormatRealToString.

Complexity Level

This filter is available on Basic Complexity Level.

See Also

  • FormatString – Creates a string according to the given format and data.