Click or drag to resize

_Str Function

X#
Convert a numeric expression to a string.

Namespace:  XSharp.RT
Assembly:  XSharp.RT (in XSharp.RT.dll) Version: 2.19
Syntax
 FUNCTION _Str(
	nValue,
	uLen,
	uDec
) AS STRING CLIPPER
Request Example View Source

Parameters

nValue (Optional)
Type: Usual
uLen (Optional)
Type: Usual
uDec (Optional)
Type: Usual

Return Value

Type: String
The returned string with always have a DOT as decimal separator.
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#
 1nNumber := 123.45
 2? Str(nNumber)                            //      123.45
 3? Str(nNumber, 4)                        // 123.
 4? Str(nNumber, 2)                        // **
 5? Str(nNumber * 10, 7, 2)                    // 1234.50
 6? Str(nNumber * 10, 12, 4)                //    1234.5000
 7? Str(nNumber, 10, 1)                    //      123.5
 8? Str(123.45, -1)                        // 123.45
 9? Str(123.45, -1, 2)                    // 123.45
10? 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#
 1? nNum
 2// displays identical to MyFunction() below
 3? MyFunction()
 4// displays identical to nNum above
 5// but internally they are not equal
 6? nNum = MyFunction()                    // FALSE
 7// after rounding they are equal
 8? Round(nNum, 0) == Round(MyFunction(), 0)    // TRUE
 9// a Val(Str()) is also rounding
10? Val(Str(nNum)) = Val(Str(MyFunction()))        // TRUE
Setting SetFloatDelta() to a higher value than before has the same effect:
X#
1SetFloatDelta(0.1)
2? 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#
1? Str(9,6,6)    => "******"
2? Str(9,6,5)    => "******"
3? Str(9,6,4)    => "9.0000"
4? Str(9,6,3)    => " 9.000"
5? Str(10,6,6)    => "******"
6? Str(10,6,5)    => "******"
7? Str(10,6,4)    => "******"
8? 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#
1USE customer NEW
2INDEX ON Str(NumOrders, 9) + Custname TO custord
See Also