Click or drag to resize

Functions.Str Method

Convert a numeric expression to a string.

Namespace:  XSharp.RT
Assembly:  XSharp.RT (in XSharp.RT.dll) Version: 2.07
Syntax
 FUNCTION Str(
	 n AS USUAL,
	 uLen AS USUAL,
	 uDec AS USUAL
) AS STRING
View Source

Parameters

n
Type: __Usual
The numeric expression to convert to a string.
uLen
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 uLen.
If uLen is not specified, SetDigit() and SetDigitFixed() determine the number of digits that are returned.
uDec
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 uLen argument. If uDec 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
The string with always a decimal separator that matches the current SetDecimalSep() setting.
- If n 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 uLen is less than the number of whole number digits in n, the result will be in scientific notation. If the result of scientific notation does not fit, a series of asterisks is returned.

Rounding is determined as follows:
- If uLen 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 uLen is specified, but uDec is omitted (no decimal places), the return value is rounded to an integer.
- If uLen and uDec 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 n 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.
See Also