Click or drag to resize

Str Function

Convert a numeric expression to a string.

Namespace:  XSharp.RT
Assembly:  XSharp.RT (in XSharp.RT.dll) Version: 2.08
Syntax
 FUNCTION Str(
	 nNumber AS USUAL,
	 nLength AS USUAL,
	 nDecimals AS USUAL
) AS STRING
View Source

Parameters

nNumber
Type: Usual
The numeric expression to convert to a string.
nLength
Type: Usual
The length of the string to return, including decimal digits, decimal point, and sign.
A value of -1 specifies that any right padding is suppressed.  However, decimal places are still returned as specified in <nDecimals>.
If <nLength> is not specified,  SetDigit() and SetDigitFixed() determine the number of digits that are returned.
nDecimals
Type: Usual
The number of decimal places in the return value.  A  value  of -1 specifies that only the significant digits to the right of the decimal point are returned (see example below).  The number of whole digits in the return value, however, are still determined by the <nLength> argument.
If <nDecimals> is not specified, SetDecimal() and SetFixed()  determine the number of decimals that are returned.
The representation of the decimal point is determined by the current setting of SetDecimalSep().

Return Value

Type: String
A string, with these exceptions: If <nNumber> is an expression that yields a numeric overflow, a runtime error is generated that could be handled by the currently installed error handler.  Either "+INF" or "-INF", which represent the biggest possible float number, is returned by the error handler. If <nLength> is less than the number of whole number digits in <nNumber>, the result will be in scientific notation.  If the result of scientific notation does not fit, a series of asterisk is returned. Rounding is determined as follows: If <nLength> is less than the number of decimal digits required for the decimal portion of the returned string, the return value is rounded to the available number of decimal places. If <nLength> is specified, but <nDecimals> is omitted (no decimal places), the return value is rounded to an integer. If <nLength> and <nDecimals> are not specified, they are taken out of the internal float format inside the FLOAT, or out of SetDigit() if the internal digit number is 0.  If SetFixed() or SetDigitFixed() is TRUE, these values are overridden by the values of SetDecimal() or SetDigit(). If SetScience() is TRUE, the return will be in scientific notation. Moreover, If SetDigit() specifies a number that is less than the number of whole number digits in <nNumber> and SetDigitFixed() is set to TRUE, the result is in scientific notation.  But if scientific notation does not fit, the result is a series of asterisks.
Remarks
Str() is commonly used to concatenate numbers to strings.  Thus, it is useful for creating codes for items, such as part numbers, from numbers and for creating order keys that combine numeric and character data. Str() is like Transform(), which formats numbers as strings using a mask instead of length and decimal specifications. The inverse of Str() is Val() which converts numbers formatted as strings to numeric values.
Examples
These examples demonstrate the range of values returned by Str(), depending on the arguments specified:
X#
nNumber := 123.45
? Str(nNumber)                                                        //      123.45
? Str(nNumber, 4)                                                // 123.
? Str(nNumber, 2)                                                // **
? Str(nNumber * 10, 7, 2)                                        // 1234.50
? Str(nNumber * 10, 12, 4)                                //    1234.5000
? Str(nNumber, 10, 1)                                        //      123.5
? Str(123.45, -1)                                                // 123.45
? Str(123.45, -1, 2)                                        // 123.45
? Str(0.45000, 12, -1)                                        //      0.45000
Often two numbers display the same results, but internally they have two different values stored in them. Thus an equality test will fail (return FALSE) unless you round each side.  Here is an example:
X#
? nNum
// displays identical to MyFunction() below
? MyFunction()
// displays identical to nNum above
// but internally they are not equal
? nNum = MyFunction()                                        // FALSE
// after rounding they are equal
? Round(nNum, 0) == Round(MyFunction(), 0)        // TRUE
// a Val(Str()) is also rounding
? Val(Str(nNum)) = Val(Str(MyFunction()))                // TRUE
Setting SetFloatDelta() to a higher value than before has the same effect:
X#
SetFloatDelta(0.1)
? nNum == MyFunction()                                        // TRUE
This functions returns a string of all asterisks when the Decimals parameter is > 0 and the Decimals parameter is  > Length-2. Also a string of all asterisks is returned when the number does NOT fit into the allocated space. Example:
X#
? Str(9,6,6)        => "******"
? Str(9,6,5)        => "******"
? Str(9,6,4)        => "9.0000"
? Str(9,6,3)        => " 9.000"
? Str(10,6,6)        => "******"
? Str(10,6,5)        => "******"
? Str(10,6,4)        => "******"
? Str(10,6,3)        => "10.000"
This example uses Str() to create an order with a compound key of order numbers and customer names:
X#
USE customer NEW
INDEX ON Str(NumOrders, 9) + Custname TO custord
See Also