IB Statements/str

From CometWiki

STR function

Syntax: STR(numeric-argument)

Discussion: The STR function converts a numeric value to a string value.

The numeric-argument may be a numeric constant, a single-element numeric variable, a numeric array element, a numeric expression, or a numeric function.

The length of the resultant value will equal the length of the numeric-argument (plus 1 character to account for the sign of an integer; plus 2 characters to account for the sign and decimal point of a real number) unless the numeric-argument is an expression.

Note: If the numeric-argument is an expression, the STR function returns 18 characters for a real number (16 digits plus a decimal point and sign) or 17 characters (16 digits plus a sign for an integer). The "precision" in the resulting string will be determined by the most precise element in the expression.

The STR function provides a sign character at the right-hand side of the converted value. If the numeric-argument contains fractional digits, the STR function inserts a decimal point in the correct location.

Note: If the result of the STR function is to be stored in a string field, the defined length of the receiving string field must include one byte for the decimal point (if applicable) and one byte for the sign character. If you do not want a sign character in the result, you can use LET statement to re-assign the result to a shorter string or use the SUB function to truncate the last character of the string.

Example 1:

 LENGTH 6.2 & LOCAL NUMBER
 LENGTH   8 & LOCAL VALUE$
 .
 VALUE$ = STR(NUMBER)

In the above example, the value contained in the numeric variable NUMBER is converted to a string and moved to the string variable VALUE$. Since NUMBER is defined with a length and precision of 6.2, VALUE$ should be defined with a length of 8 (to account for the 6 digits, the decimal point, and the trailing sign).

For example, if NUMBER equals 1234.56 (a numeric quantity), then VALUE$ will equal "1234.56 " (a string; note the trailing blank space indicating a positive number).

Example 2:

 LENGTH 4.0 & LOCAL A
 LENGTH   5 & LOCAL Z$
 !
 Z$ = STR(A)

In this example, A is defined with a length and precision of 4.0 (an integer), so Z$ should be defined with a length of 5 (to account for the four digits and the sign; no space is required for a decimal point). For example, if A equals 5000-, then Z$ will equal "5000-" (note no decimal point and the trailing minus sign).