xHarbour Reference Documentation > Function Reference

Transform()

Converts values to a PICTURE formatted character string.

Syntax

Transform( <xValue>, <cPicture> ) --> cFormattedString

Arguments

<xValue>

This is a value of data type Character, Date, Logic, Memo or Numeric to be formatted.

<cPicture>

This is a PICTURE formatting string defining the formatting rules (see below).

Return

The function returns a character string holding the formatted value of <xValue>.

Description

Transform() is used to convert values of simple data types (C,D,L,M,N) to formatted character strings. Formatting rules are defined with the second parameter <cPicture>. This picture string may consist of characters defining a picture function, or characters defining a picture mask, or both. If picture function and mask are present in the picture string, the picture function must be first and the mask characters must be separated from the picture function by a single blank space.

Picture function

A picture function specifies formatting rules for the entire output string. It must begin with the @ sign followed by one or more letters listed in the table below:

Picture function characters

Function	Formatting rule
B	Formats numbers left-justified
C	Adds CR (credit) after positive numbers
D	Formats dates in SET DATE format
E	Formats dates and numbers in British format
L	Pads numbers with zeros instead of blank spaces
R	Nontemplate characters are inserted
X	Adds DB (debit) after negative numbers
Z	Formats zeros as blanks
(	Encloses negative numbers in parentheses
!	Converts alphabetic characters to uppercase

Picture mask

The picture mask must be separated by a single space from the picture function. When no picture function is used, the picture string is identical with the picture mask. The mask defines formatting rules for individual characters in the output string. Characters from the following table can be used. The position of a character of a picture mask specifies formatting for the character of the output string at the same position. An exception is the @R function which causes non-mask characters being inserted into the output string.

Picture mask characters

Charactere	Formatting rule
A,N,X,9,#	Formats digits for any data type
L	Formats logicals as "T" or "F"
Y	Formats logicals as "Y" or "N"
!	Converts alphabetic characters to uppercase
$	Adds a dollar sign in place of a leading space in a number
*	Adds an asterisk in place of a leading space in a number
.	Specifies a decimal point position
,	Specifies a comma position

Info

See also:	@...SAY, DtoC(), Lower(), PadC() | PadL() | PadR(), Str(), Upper(), Val()
Category:	Conversion functions
Source:	rtl\transfrm.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example demonstrates different formatting results of Transform()

   PROCEDURE Main
      LOCAL nGain  := 8596.58
      LOCAL nLoss  := -256.50
      LOCAL cPhone := "5558978532"
      LOCAL cName  := "Jon Doe"

      ? Transform( 8596.58, "@E 9,999.99" )   // result: 8.596,58

      ? Transform( 8596.58, "999,999.99" )    // result:   8,596.58
      ? Transform( 8596.58, "@L 999,999.99" ) // result: 008,596.58

      ? Transform( -256.50, "@)" )            // Result: (256.50)

      ? Transform( "5558978532", "@R (999)999-9999" )
                                              // Result: (555)897-8532

      ? Transform( "xharbour", "@!" )         // Result: XHARBOUR
      ? Transform( "xharbour", "A!AAAAAA" )   // Result: xHarbour
   RETURN