You are here: Start » Filter Reference » Basic » String » FormatRealToString

FormatRealToString

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
inReal	Real		Input real
inIntegerDigitCount	Integer	0 - 1000	How many characters the integer part of the input real should have at least
inFractionalDigitCount	Integer	0 - 100	How many characters the fractional part of the input real should have
inDecimalMark	String		The symbol used to separate the integer part from the fractional part of the number
inTrailingCharacter	String		Defines the trailing character
inForceSignPrinting	Bool		Forces printing the sign of the number even if the number is positive
inSuffix	String		Defines a suffix. Generally it is an unit of value (e.g. mm)
outString	String		Output string

Examples

Description of usage of this filter can be found in examples and tutorial: Calibration World Coordinates On Original Images, Calibration World Coordinates With Remapped Images.


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