STR

STR returns the string representation of a floating point number in decimal notation.

The number passed to the STR function must use . (period) as the decimal separator and , (comma) as the thousand separator. Any other decimal or thousand separators will cause incorrect results.

This function is valid in both TM1® rules and TurboIntegrator processes.

Syntax

STR(number, length, decimal)

Table 1. STR arguments
Argument	Description
number	The floating point number being converted to a string. This number can contain a positive or negative sign. This number can contain decimal places.
length	The minimal length of the string to be returned., including sign, separators, decimal, or decimal places. The length argument value should be a positive number greater than 0. If the length argument value is 0, the function returns an empty string for zero or empty values when the decimal argument is also set to 0, or returns a representation without a leading 0 before the decimal point if the number is only a fraction. If the length argument value is a negative number, the function returns an empty string. If the count of digits in the number is less than the length argument value, the function inserts leading blank spaces to attain this length after inserting sign, separators, decimal, or decimal places. If the count of digits in the whole number exceeds the length argument value and the decimal argument value is 0, the function truncates the whole number to attain this length. If the count of digits in the number exceeds the length argument value and the decimal argument value is greater than 0, the function preserves the whole number and uses the specified decimal places.
decimal	The number of decimal places to include in the string representation. If this parameter is 0, a decimal point is not included. If the number specified has more decimal places than the decimal argument, the function result is rounded. If a negative number with decimals is specified, the function rounds the number accordingly (for example, -3 rounds to thousands and -6 rounds to millions), but returns the full number with trailing zeros to reflect the rounding.

All arguments are required and you cannot pass empty argument values.

The STR function returns a string representation that uses a period (.) as the decimal separator. STR is the counterpart of the NUMBR function where NUMBR(STR(x, length, decimal)) returns the original value (x) when provided the number of decimals suffices to represent the fraction. The returned string representation does not contain any thousand separator. To format numbers, use StringToNumber or StringToNumberEx.

Note: There is a limitation when using STR with large floating point values. If the count of whole number digits in the number argument value exceeds the length argument value by more than 5, the function returns an empty string. For example, STR(14723017.2245, 4, 2) returns "14723017.22". The whole number portion of the number argument value has 8 digits, which is not more than 5 greater than the length argument value of 4 (8<5+4). However, STR(14723017.2245, 2, 2) returns an empty string, because the whole number portion of the number argument value has 8 digits, which is more than 5 greater than the length argument value of 2 (8>5+2)

Examples

Function call	Number	Length	Decimal	Result
STR(3.14159, 6, 2)	3.14159	6	2	3.14
STR(-3.14159, 6, 0)	-3.14159	6	0	-3
STR(3.14159, 5, 3)	3.14159	5	3	3.142
STR(1000000, 4, 0)	1000000	4	0	1000 Note that the number is truncated.
STR(1000000, 4, 2)	1000000	4	2	1000000.00 Note that the number is not truncated because decimal is specified.
STR(10, 2, 4)	10	2	4	10.0000
STR(120536.74391, 8, 0)	120536.74391	8	0	120536 The result includes left padding of two spaces to attain the specified length of 8.
STR(120536.74391, 5, 0)	120536.74391	5	5	12053 The count of digits in the whole number exceeds the length argument value and the decimal argument value is 0, so the function truncates the whole number to attain the specified length of 5.