@Text (Formula Language)
Converts any value to a text string.
Syntax
@Text( value ; format-string )
Parameters
value
Number, time-date, text, list thereof, or rich text. The value you want to convert to text.
Note: Conversion of rich text is new with Release 6.
format-string
Text or text list. Optional. Up to four format-strings (see table that follows). These determine how the text is returned. If the value is already a text data type, the format-string is ignored.
Return value
textValue
Text or text list. The value you specified, converted to text. If you used any format-strings, they are applied.
@Text with time-date components
There are four separate categories of time-date, format-string components. You can include up to four components, but only one from each category.
| Symbol | Meaning |
|---|---|
| D0 | Month, day and year |
| D1 | Month and day, year if it is not the current year |
| D2 | Month and day |
| D3 | Month and year |
| T0 | Hour, minute, and second |
| T1 | Hour and minute |
| Z0 | Always convert time to this zone |
| Z1 | Display zone only when it is not this zone |
| Z2 | Display zone always |
| S0 | Date only |
| S1 | Time only |
| S2 | Date and time |
| S3 | Date, time, Today, or Yesterday |
| Sx | Use when you cannot predict the exact format of the value being passed, but you know that it is either a time, a date, or both. |
@Text with number values
For number values, compose a format-string by combining any of the following components into a string.
| Symbol | Meaning |
|---|---|
| G | General format (significant digits only) |
| F | Fixed format (set number of decimal places) |
| S | Scientific format (E notation) |
| C | Currency format (two decimal places) |
| , | Punctuated at thousands (using U.S. format) |
| % | Percentage format |
| () | Parentheses around negative numbers |
| number | Number of digits of precision |
Usage
If the parameter is a list, the function operates on each element of the list, and the return value is a list with the same number of elements.
Once a number value is converted to text, you will not be able to use the number for arithmetic calculations.
Rich text conversion loses attachments and all formatting except tabs and spaces. When rich text is converted in a document, the document must be saved before the conversion becomes visible.
Rich text conversion does not work in column formulas. Use @Abstract to convert the contents of a rich text field to plain text. Then reference the plain text field in the view. For example, if you add the following code to a hidden computed field called plainText, you can then set the default value of the view column to "plainText" to display the contents of the RTField:
@Abstract([TextOnly];15360;"";"RTField")
Use caution if using @Text to convert numbers or dates in a column. In databases hosted by a server, the numbers and dates always display using the format settings of the hosting server's operating system. Also, if the date or number format settings of either the client accessing the database or server hosting the database change, you may need to entirely rebuild the view.
Examples
- This example returns 123.45.
@Text(123.45)
- This example returns $800.00 if the value in the Sales field is 800.
@Text(Sales;"C,2")
- This example returns 8.00E+02.
@Text(800;"S")
- This example returns 8.00E+02 and -6.00E+02 in a list.
@Text(800 : (-600);"S")
- This example returns 04/11/93 10:43 AM.
@Text(@Now)
- This example returns 04/11.
@Text(@Now;"D1S0")
- This example returns 10:43:30 AM.
@Text(@Now;"D1S1")
- This example returns 04/93 10:43 AM.
@Text(@Now;"D3T1")
- This example returns the rich-text Body field stripped of attachments and formatting.
@Text(Body)
- To convert a number date (in the ShipDate field) into a written date, you can use the following code. If ShipDate contains [08/31/2002], the result is "August 31, 2002."
@If( @IsTime(ShipDate);
@Text(@Select(@Month(ShipDate); "January"; "February"; "March"; "April"; "May"; "June"; "July"; "August"; "September"; "October"; "November"; "December")) + " " +
@Text(@Day(ShipDate)) + ", " + @Text(@Year(ShipDate));
"No date given")