STR( )
Returns the character string equivalent of a specified numeric expression.
Syntax
STR(<expN> [, <length expN> [, <decimals expN> [, <expC>]]])
<expN>
The numeric expression to return as a character string.
<length expN>
The length of the character string to return. The valid range is 1 to 20, inclusive, and includes a decimal point, decimal digits, and minus sign characters. The default is 10. If <length expN> is smaller than the number of integer digits in <expN>, STR( ) returns asterisks (*).
<decimals expN>
The number of characters to reserve for decimal digits. The default and lowest allowable value is 0. If you do not specify a value for <decimals expN>, STR( ) rounds <expN> to the nearest whole number. If you want to specify a value for <decimals expN>, you must also specify a value for <length expN>.
<expC>
The character to pad the beginning of the returned character string with when the length of the returned string is less than <length expN> digits long. The default pad character is a space. If you want to specify a value for <expC>, you must also specify values for <length expN> and <decimals expN>. You can specify more than one character for <expC>, but STR( ) uses only the first one.
Description
Use STR( ) to convert a number to a string, so you can manipulate it as characters. For example, you can index on a numeric field in combination with a character field by converting the numeric field to character with STR( ).
dBASE Plus rounds and pads numbers to fit within parameters you set with <length expN> and <decimals expN>, following these rules:
If <decimals expN> is smaller than the number of decimals in <expN>, STR( ) rounds to the most accurate number that will fit in <length expN>. For example, STR(10.765,5,1) returns " 10.8" (with a single leading space), and STR(10.765,5,2) returns "10.77".
If <length expN> isn't large enough for <decimals expN> number of decimal places, STR( ) rounds <expN> to the most accurate number that will fit in <length expN>. For example, STR(10.765,4,3) returns "10.8".
If <decimals expN> is larger than the number of decimals in <expN>, and <length expN> is larger than the returned string, STR( ) adds zeros (0) to the end of the returned string. dBASE Plus only adds enough zero to bring the number of decimal digits to a maximum of <decimals expN>.
If the returned string is still shorter than <length expN>, dBASE pads the left to fill to the length of <length expN>. For example, STR(10.765,8,6) returns "10.76500" for a returned length of 8; STR(10.765,7,6) returns "10.7650" for a returned length of 7; and STR(10.765,12,6) returns " 10.765000" (with three leading spaces) for a returned length of 12.
To remove the leading spaces created by STR( ), use LTRIM( ). If you concatenate a number to a string with the + or - operators, dBASE Plus automatically converts the number to a string, using the number of decimal places specified by SET DECIMALS, and removes the leading spaces.