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

FormatRealToString

Header:	STD.h
Namespace:	fil
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.

Syntax

void fil::FormatRealToString
(
	const float inReal,
	const int inIntegerDigitCount,
	const int inFractionalDigitCount,
	const ftl::String& inDecimalMark,
	const ftl::String& inTrailingCharacter,
	const bool inForceSignPrinting,
	const ftl::String& inSuffix,
	ftl::String& outString
)

Parameters

Name	Type	Range	Default	Description
inReal	const float			Input real
inIntegerDigitCount	const int	0 - 1000		How many characters the integer part of the input real should have at least
inFractionalDigitCount	const int	0 - 100	3	How many characters the fractional part of the input real should have
inDecimalMark	const String&		\".\"	The symbol used to separate the integer part from the fractional part of the number
inTrailingCharacter	const String&		\"0\"	Defines the trailing character
inForceSignPrinting	const bool		False	Forces printing the sign of the number even if the number is positive
inSuffix	const String&		\"\"	Defines a suffix. Generally it is an unit of value (e.g. mm)
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 FisFilter_ConcatenateStrings.

Errors

List of possible exceptions: