Function Transform() | Xbase++

Functions and Directives Functions and Directives

Transforms a value to a formatted character string.

Transform( <Expression>, <cSayPicture> ) --> cFormattedString

<Expression> is an expression whose value can be of data type "character", "numeric", "logical" or "date".

<cPicture> is a character string containing the specification of how the value of <Expression> is formatted. <cPicture> can contain a formatting mask and/or a PICTURE function.

The return value of Transform() is a character string containing the value <Expression> formatted according to the specification given in <cPicture>.

The conversion function Transform() accepts a value, transforms it to a character string, formats this character string according to the specification in <Picture>, and returns the formatted character string. Transform() processes values of data type "character", "numeric", "logical" and "date". It is a versatile function which is often used in formatting data for output on the screen or to the printer.

PICTURE function

The characters for a PICTURE function must appear at the start of the character string <cPicture> and must be prefaced with the character @ (Chr(64)). After the character @, one or more of the characters which define specific formatting rules can be included. The valid characters are listed in the following table. Each stands for a specific formatting rule:

Function	Data type	formatting
B	N	Displays number left justified
C	N	Displays CR (Credit) behind positive numbers
D	C	Displays character strings in the SET DATE format
L<c>	N	Fills numeric values from the left with the character <c>
R	C	Includes unknown formatting characters in the display
X	N	Displays DB (Debit) behind negative numbers
Z	N	When the value is zero, only blank places are displayed
(	N	Displays negative numbers in parentheses with leading blank places
)	N	Displays negative numbers in parentheses without leading blank places
$	N	Places country-specific currency characters in front of a number
!	C	Transforms alphabetical characters to upper case

Characters for the PICTURE function are case-sensitive.

Characters for a PICTURE mask can follow the characters for the PICTURE function. When a mask is also specified, the PICTURE function and mask must be separated from one another by a single blank space.

PICTURE mask

A PICTURE mask contains formatting rules for each individual character of the transformed value. As with the PICTURE function, formatting characters are specified which define a specific formatting rule. Each character in the PICTURE mask corresponds to a character in the return character string. The possible formatting characters for a PICTURE mask are listed in the following table:

Character	Formatting rule
A,N,X,9,#	Displays characters for each data type
L	Displays logical values as "T" or "F"
Y *)	Displays logical values as "Y", "J" or "N"
!	Transforms alphabetical characters to upper case
$	Replaces leading blank spaces in numbers with a dollar sign ($)
*	Replaces leading blank spaces in numbers with a star (*)
.	Marks position for a decimal point
,	Marks position for a comma
Display is country-specific, see SetLocale()

Any characters in the PICTURE mask which are not listed in this table are copied into the return character string. When the PICTURE function @R is used, these characters are inserted into the return character string, otherwise they replace characters in the return character string.

Country-specific formatting of numbers

When transforming numbers to character strings, Transform() uses the number format set by the system configuration which results in a decimal point or comma after each setting. When converting a numeric to a string and a decimal point is desired instead of a decimal comma regardless of the system configuration, the numeric value should be transformed by the function Str() instead of Transform(). Example:

nNumber  := 12.345 
cStringA := Transform( nNumber, "@N" )  // may result in 
                                        // "12,345" or "12.345" 
cStringB := Str( nNumber, 6, 3 )        // is always "12.345" 

nNumberA := Val( cStringA ) * 10        // may result in 
                                        // 120 or 123.45 
nNumberB := Val( cStringB ) * 10        // is always 123.45

When using Transform() to perform conversions and the comma is defined as the delimiter for decimal places in the system settings, a comma is inserted into the formatted result string. Changing the character string back to a numeric value using the function Val() may then lead to erroneous results since Val() only works with a decimal point and not with a decimal comma.

Transform()

// The example demonstrates how various values can be 
// formatted by Transform(). 

PROCEDURE Main 
   LOCAL xValue 

   xValue := "Xbase++" 
                                            ** result 
   ? Transform( xValue, "@!")               // XBASE++ 
   ? Transform( xValue, "@R X-X-X-X-X-X-X") // X-b-a-s-e-+-+ 

   xValue := -1234.56 

   ? Transform( xValue,    "99,999.99")     // -1,234.56 
   ? Transform( xValue, "*********.**")     // ****-1234.56 
   ? Transform( xValue, "$$$$$$$$$.$$")     // $$$$-1234.56 
   ? Transform( xValue, "@("          )     // (     1234.56) 
   ? Transform( xValue, "@$ 999,999.99" )   // $ -1,234.56 
   ? Transform( xValue, "@Lx 999,999.99")   // xx-1,234.56 

   xValue := 123456 

   ? Transform( xValue, "@C"          )     //     123456 CR 

   ? Transform( xValue, "99 - 99 - 99")     // 12 - 34 - 56 

   xValue := .T. 

   ? Transform( xValue, "L" )               // T 
   ? Transform( xValue, "Y" )               // Y 

RETURN

Function Transform() Foundation