Functions and Directives Functions and Directives

Function Str() Foundation

Converts the value of a numeric expression to a character string.

Syntax
Str( <nValue>, [<nLength>], [<nDecimals>] ) --> cString
Parameters
<nValue>
<nValue> is a numeric expression whose value is converted to a character string.
<nLength>
<nLength> specifies the length of the character string returned. The length includes the sign character, decimal point and decimal places.
<nDecimals>
<nDecimals> specifies the number of decimal places for the returned character string.
Return

The function Str() formats a numeric value <nValue> as a character string. The length of the character string returned from Str() depends on the optional arguments <nLength> and <nDecimals>. When neither of the arguments are included, the numeric value is formatted according to the following rules:

Default formatting of Str()
Numeric expression Length of the return character string
Expressions/Constants At least ten digits plus decimal places
Field variable Field length including decimal places
Month()/Day() 3 digits
RecNo() 7 digits
Val() At least 3 digits
Year() 5 digits

Description

The conversion function Str() converts a numeric value to a character string. It resembles the function Transform() which converts a value to a character string according to a given formatting mask. Str() works according to firm rules and only converts numeric values to character strings. Str() is frequently used when numeric values are output or when a character value and a numeric value must be combined in an index expression.

Str() formats numeric values and depends on the optional arguments <nLength> and <nDecimals>. The numeric value is rounded when <nDecimals> is less than the number of decimal places in <nValue>. The default value for <nDecimals> is zero. This means that if this argument is missing, <nValue> is first rounded to an integer and then changed to a character string. When the value for <nLength> is smaller than the number of places in front of the decimal point of <nValue>, Str() returns asterisks (*) in place of digits (as with a numeric overflow).

Val() is the reverse of the function Str() and converts a character string to a numeric value.

Examples
Str() 
// The example shows various return values of Str() depending 
// on the optional arguments 'nLength' and 'nDecimals' 

PROCEDURE Main 
   LOCAL  nValue:= 678.9136 

   ? Str(nValue)               // result:        678.9136 

   ? Str(nValue, 1 )           // result: * 
   ? Str(nValue, 2 )           // result: ** 
   ? Str(nValue, 3 )           // result: 679 
   ? Str(nValue, 4 )           // result:  679 
   ? Str(nValue, 5 )           // result:   679 

   ? Str(nValue, 5, 1 )        // result: 678.9 
   ? Str(nValue, 6, 2 )        // result: 678.91 
   ? Str(nValue, 7, 3 )        // result: 678.914 
   ? Str(nValue, 8, 4 )        // result: 678.9136 

   ? Str(nValue, 10, 0)        // result:        679 
   ? Str(nValue, 10, 1)        // result:      678.9 
   ? Str(nValue, 10, 2)        // result:     678.91 
   ? Str(nValue, 10, 3)        // result:    678.914 
   ? Str(nValue, 10, 4)        // result:   678.9136 

RETURN
Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.