STR( ) Function

  • Article

Returns the character equivalent of a numeric expression.

STR(nExpression [, nLength [, nDecimalPlaces]])

Parameters

  • nExpression
    Specifies the numeric expression to evaluate.

  • nLength
    Specifies the length of the character string returned. If nLength is omitted, nLength defaults to 10 characters.

    Note

    If the expression contains a decimal point, the length includes one character for the decimal point and one character for each digit in the character string.

  • nDecimalPlaces
    Specifies the number of decimal places in the character string returned. To specify the number of decimal places using nDecimalPlaces, you must include nLength. If nDecimalPlaces is omitted, the number of decimal places defaults to zero (0).

    Note

    Visual FoxPro contains a limit of 16 digits of precision in numeric calculations. For more information about numeric precision in Visual FoxPro, see Visual FoxPro System Capacities.

Return Value

Character data type. STR( ) returns a character string equivalent to the specified numeric expression.

Depending on certain conditions, STR( ) can return the following:

  • If you specify fewer decimal places than exist in nExpression, the return value is rounded up. To round results to the nearest decimal place instead of upward, include the ROUND( ) function. For more information, see ROUND( ) Function.

  • If nExpression is an integer, and nLength is less than the number of digits in nExpression, STR( ) returns a string of asterisks, indicating numeric overflow.

  • If nExpression contains a decimal point, and nLength is equal to or less than the number of digits to the left of the decimal point, STR( ) returns a string of asterisks, indicating numeric overflow.

  • If nLength is greater than the length of the value evaluated by nExpression, STR( ) returns a character string padded with leading spaces.

  • If nExpression has Numeric or Float type, and nLength is less than the number of digits in nExpression, and , STR( ) returns a value using scientific notation.

Examples

Example 1

In the following example, STR( ) evaluates 1.154994 as a character expression, specifies a length of 8 characters and the same number of decimal places that the specified expression contains, and displays 1.154994 using the ? command.

? STR(1.154995,8,6)

Example 2

In the following example, STR( ) evaluates 1.154994 as a character expression and specifies a length of 8 characters and 2 decimal places, four fewer decimal places than the specified expression contains. STR( ) displays 1.16 using the ? command, which represents 1.154994 rounded upward.

? STR(1.154995,8,2)

Example 3

In the following example, STR( ) includes the ROUND( ) function, evaluates 1.154994 as a character expression, and specifies a length of 8 characters 2 decimal places, four fewer decimal places than the specified expression contains. STR( ) displays 1.15 using the ? command, which represents 1.154994, rounded to the nearest significant digit.

? STR(ROUND(1.154995,2),8,2)

See Also

Reference

VAL( ) Function
STRCONV( ) Function

Concepts

Creating Numeric Expressions

Other Resources

Functions
Language Reference (Visual FoxPro)