STRING( ) function
Converts a numeric value to a character string.
Syntax
STRING(number, length <,format>)
Parameters
| Name | Type | Description |
|---|---|---|
| number |
numeric |
The numeric value to convert to a string. |
| length | numeric |
The length of the output string in characters.
Ensure that the length you specify provides enough space for the longest numeric value in a field, including any non-numeric format characters if you specify the optional format parameter. |
| format
optional |
character |
The format to apply to the output string. format must be enclosed in double quotation marks. For example, "(9,999.99)" Use the optional format parameter to add formatting to the output string that is not present in the source data. You can add a dollar sign, a percent sign, one or more decimal placeholders, a thousands separator, parentheses, and so on. Note Non-numeric format characters that you specify increase the length of number. |
Output
Character.
Examples
Basic examples, output not formatted
Numeric value 125.2
Returns " 125.2":
STRING(125.2, 6)
The output string is padded with one leading space because the length value is 6, which is one character longer than the number of digits and format characters in number.
Numeric value -125.2
Returns "25.2":
STRING(-125.2, 4)
The output string is truncated because the length value is 4, which is two characters shorter than the number of digits and format characters in number.
Returns " -125.2":
STRING(-125.2, 7)
The output string is padded with one leading space because the length value is 7, which is one character longer than the number of digits and format characters in number.
Basic examples, output formatted
Numeric value 125.2
Returns "25.20":
STRING(125.2, 6, "(9,999.99)")
The output string is truncated because the length value is 6, which is one character shorter than the number value after the specified format is applied.
Returns "125.20":
STRING(125.2, 7, "(9,999.99)")
Note
Starting from the right, the characters you specify for format are included in the calculation of the length of number even if a format character is not required for a specific instance of number. In the examples above, the right-hand parenthesis is counted as a character even though it is not required for a positive value in number.
Numeric value -125.2
Returns " (125.20)":
STRING(-125.2, 10, "(9,999.99)")
The output string is padded with two leading spaces because the length value is 10, which is two characters longer than the number value after the specified format is applied.
Basic example, field input
Returns numeric values in the Employee_number field as character strings with a length of 10 characters. If required, the output string is padded or truncated:
STRING(Employee_number, 10)
Remarks
Formatting the output string
You can format the output string to display formatting that might be missing in the source data.
Placeholder digits in the format
In the format that you specify, the digit 9 acts as a placeholder for digits. Ensure that you specify enough placeholder digits to account for the longest numeric value in a field. For example, if a field contains amounts up to $5,000,000, with two decimal places, you need to specify nine placeholder digits: "$9,999,999.99"
How the format affects the minimum required output string length
The value you specify for length must, at a minimum, be long enough to contain all the digits in the longest value in a field, as well as any format characters that you specify.
If you want to add a dollar sign, and thousands separators, to the values in the field containing amounts up to $5,000,000, you need to specify at least 13 for length: 9 digits + 4 non-numeric format characters.
Returns numeric values in the Amount field as character strings with the specified format displayed.
STRING(Amount, 13, "$9,999,999.99")
Returns $4,789,123.50, as a character string:
STRING(4789123.50, 13, "$9,999,999.99")
Related functions
The STRING( ) function is the opposite of the VALUE( ) function, which converts character data to numeric data.
