Transform Function (Logic, String) |  |
Convert any value into a formatted string.
Namespace: XSharp.RT
Assembly: XSharp.RT (in XSharp.RT.dll) Version: 2.21
SyntaxRequest Example
View Source
A formatted string as defined by cSayPicture.
Parameters
- uValue
- Type: Logic
The value to format.
This expression can be any valid X# data type except array, code block, object, and NIL. - cSayPicture
- Type: String
A string of picture and template characters that describes the format of the returned string.
Return Value
Type: StringA formatted string as defined by cSayPicture.
Remarks
Transform() is a conversion function that formats character, date, logical, and numeric values according to a specified picture string that includes a combination of picture function and template strings. Transform() formats data for output to the screen or the printer in the same manner as the PICTURE clause of the @...SAY command.
To convert the transformed string back to its original value, use Unformat(). Function string:
A picture function string specifies formatting rules that apply to the Transform() return value as a whole, rather than to particular character positions within uValue.
The function string consists of the @ character, followed by one or more additional characters, each of which has a particular meaning (see table below).
If a function string is present, the @ character must be the leftmost character of the picture string, and the function string must not contain spaces.
A function string can be specified alone or with a template string.
If both are present, the function string must precede the template string, and the two must be separated by a single space. Function Action B Displays numbers left-justified C Displays CR after positive numbers D Displays date in SET DATE format E Displays date in British format R Nontemplate characters are inserted X Displays DB after negative numbers Z Displays zeros as blanks ( Encloses negative numbers in parentheses ! Converts alphabetic characters to uppercase Template string:
A picture template string specifies formatting rules on a character by character basis.
The template string consists of a series of characters, some of which have special meanings (see table below).
Each position in the template string corresponds to a position in the value of the uValue argument. Because Transform() uses a template, it can insert formatting characters such commas, dollar signs, and parentheses. Characters in the template string that have no assigned meanings are copied literally into the return value.
If the @R picture function is used, these characters are inserted between characters of the return value; otherwise, they overwrite the corresponding characters of the return value.
A template string can be specified alone or with a function string.
If both are present, the function string must precede the template string, and the two must be separated by a single space. Template Action A,N,X,9,# Displays digits for any data type L Displays logicals as "T" or "F" Y Displays logicals as "Y" or "N" ! Converts an alphabetic character to uppercase $ Displays a dollar sign in place of a leading space in a numeric * Displays an asterisk in place of a leading space in a numeric . Specifies a decimal point position , Specifies a comma position
To convert the transformed string back to its original value, use Unformat(). Function string:
A picture function string specifies formatting rules that apply to the Transform() return value as a whole, rather than to particular character positions within uValue.
The function string consists of the @ character, followed by one or more additional characters, each of which has a particular meaning (see table below).
If a function string is present, the @ character must be the leftmost character of the picture string, and the function string must not contain spaces.
A function string can be specified alone or with a template string.
If both are present, the function string must precede the template string, and the two must be separated by a single space. Function Action B Displays numbers left-justified C Displays CR after positive numbers D Displays date in SET DATE format E Displays date in British format R Nontemplate characters are inserted X Displays DB after negative numbers Z Displays zeros as blanks ( Encloses negative numbers in parentheses ! Converts alphabetic characters to uppercase Template string:
A picture template string specifies formatting rules on a character by character basis.
The template string consists of a series of characters, some of which have special meanings (see table below).
Each position in the template string corresponds to a position in the value of the uValue argument. Because Transform() uses a template, it can insert formatting characters such commas, dollar signs, and parentheses. Characters in the template string that have no assigned meanings are copied literally into the return value.
If the @R picture function is used, these characters are inserted between characters of the return value; otherwise, they overwrite the corresponding characters of the return value.
A template string can be specified alone or with a function string.
If both are present, the function string must precede the template string, and the two must be separated by a single space. Template Action A,N,X,9,# Displays digits for any data type L Displays logicals as "T" or "F" Y Displays logicals as "Y" or "N" ! Converts an alphabetic character to uppercase $ Displays a dollar sign in place of a leading space in a numeric * Displays an asterisk in place of a leading space in a numeric . Specifies a decimal point position , Specifies a comma position
Examples
This example formats a number into a currency format using a template:
This example formats a string using a function:
X#
1? Transform(123456, "$999,999") // Result: $123,456
X#
1? Transform("to upper", "@!") // Result: TO UPPER
See Also