$FUNCNAME$
  TRANSFORM()
$CATEGORY$
  STRING,NUMERIC,DATE/TIME,LOGICAL
$SUMMARY$
   Convert any value into a formatted character string
$LANG_RU$
         .
$SYNTAX$
     TRANSFORM(<exp>, <cSayPicture>) --> cFormatString
$LANG_RU$
     TRANSFORM(<>,<SAY-> -->  
$ARGUMENTS$
     <exp> is the value to be formatted.  This expression can be any
     valid xClipper data type except array, code block, and NIL.

     <cSayPicture> is a string of picture and template characters that
     describes the format of the returned character string.
$LANG_RU$
     <> -   ,   
       xClipper ,  ,    NIL.

     <SAY-> -   ,   
      .
$RETURNS$
     TRANSFORM() converts <exp> to a formatted character string as defined by
     <cSayPicture>.
$LANG_RU$
     TRANSFORM()  <>   , 
       ,   <SAY->.
$DESCRIPTION$
     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.

       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 <exp>.
	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 may 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.

	<PRE>TRANSFORM() Functions
	---------------------------------------------------------------------
	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
	---------------------------------------------------------------------
	</PRE>

       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 <exp> argument.
	Because TRANSFORM() uses a template, it can insert formatting
	characters such as 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 may 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.

	<PRE>TRANSFORM() Templates
	---------------------------------------------------------------------
	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
	---------------------------------------------------------------------
	</PRE>
$LANG_RU$
     TRANSFORM() -  ,   CHARACTER,
     DATE, LOGICAL  NUMERIC      ,
          . TRANSFORM()
        ,    PICTURE  
     @...SAY.  TRANSFORM()     
          .

       .     ,
           ,   
         <>.      @ 
              , 
            (  ).  
         @    .   
        .        
        .      
              
       .

       .     
           .     
       ,       (
        ).       
         <>.    ,  
         ,   
        .     @R, 
            , 
             
        .       
         .      
              
       .

       <PRE> TRANSFORM()
       -------------------------------------------------------------------
            
       -------------------------------------------------------------------
       B            ,  
       C            CR   
       D               SET DATE
       E               BRITISH ()
       R            ,    
       X            DB   
       Z              
       (               
       !                
       -------------------------------------------------------------------
       </PRE>

	<PRE> TRANSFORM()
       -------------------------------------------------------------------
                
       -------------------------------------------------------------------
       A.N.X.9.#           
       |                : ""  "F"
       Y                : "Y"  "N"
       !                   
       $                     
       *                    
       .                 
       ,                
       -------------------------------------------------------------------
       </PRE>
$EXAMPLES$
       This example formats a number into a currency format using a
	template:

	? TRANSFORM(123456, "$999,999")    // Result: $123,456

       This example formats a character string using a function:

	? TRANSFORM("to upper", "@!")      // Result: TO UPPER
$LANG_RU$
            , 
       :

       ? TRANSFORM(123456, "$999,999")       // : $123,456

          ,  :

       ? TRANSFORM("to upper", "@!")         // : TO UPPER
$SEEALSO$
  PAD(),STR(),UPPER(),LOWER()
$END$
