Convert a numeric expression to a string.
XSharp.RT (in XSharp.RT.dll) Version: 2.6
Syntax Request Example
nNumber AS USUAL := NIL,
nLength AS USUAL := NIL,
nDecimals AS USUAL := NIL
) AS STRING
public static string Str(
Usual nNumber = null,
Usual nLength = null,
Usual nDecimals = null
- nNumber (Optional)
- Type: Usual
The numeric expression to convert to a string.
- nLength (Optional)
- 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 (Optional)
- 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().
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.
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.
These examples demonstrate the range of values returned by Str(), depending on the arguments specified:
1nNumber := 123.45
3? Str(nNumber, 4)
4? Str(nNumber, 2)
5? Str(nNumber * 10, 7, 2)
6? Str(nNumber * 10, 12, 4)
7? Str(nNumber, 10, 1)
8? Str(123.45, -1)
9? Str(123.45, -1, 2)
10? Str(0.45000, 12, -1)
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:
6? nNum = MyFunction()
8? Round(nNum, 0) == Round(MyFunction(), 0)
10? Val(Str(nNum)) = Val(Str(MyFunction()))
Setting SetFloatDelta() to a higher value than before has the same effect:
2? nNum == MyFunction()
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.
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:
1USE customer NEW
2INDEX ON Str(NumOrders, 9) + Custname TO custord