Str Function |  |
Convert a numeric expression to a string.
Namespace: XSharp.RT
Assembly: XSharp.RT (in XSharp.RT.dll) Version: 2.21
SyntaxRequest Example
View Source
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.
Parameters
- 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().
Return Value
Type: StringA 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:
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:
Setting SetFloatDelta() to a higher value than before has the same effect:
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:
This example uses Str() to create an order with a compound key of order numbers and customer names:
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
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
X#
1SetFloatDelta(0.1) 2? nNum == MyFunction() // TRUE
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"
X#
1USE customer NEW 2INDEX ON Str(NumOrders, 9) + Custname TO custord
See Also