FiveTech Support Forums

 TRANSFORM()
 Convert any value into a formatted character string
------------------------------------------------------------------------------
 Syntax

     TRANSFORM(<exp>, <cSayPicture>) --> cFormatString

 Arguments

     <exp> is the value to be formatted.  This expression can be any
     valid CA-Clipper 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.

 Returns

     TRANSFORM() converts <exp> to a formatted character string as defined by
     <cSayPicture>.

 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.

        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
        ---------------------------------------------------------------------

     ¦  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.

        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
        ---------------------------------------------------------------------

 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

     PICTURE: When you specify the PICTURE clause for a GET, the
     character string specified by <cGetPicture> controls formatting and edit
     validation.  The picture string controls the display format like a SAY
     picture.  It also controls the way the user can edit the buffer.  A
     picture string consists of two distinct parts, a function string and a
     template string, either or both of which may be present.

     ¦  Function string: A PICTURE function string specifies
        formatting or validation rules which apply to the GET's display value
        as a whole, rather than to particular character positions within it.
        The function string consists of the @ character, followed by one or
        more additional characters, each of which has a particular meaning
        (see the following table).  The function string must be the first
        element of a PICTURE clause and cannot 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.

        GET PICTURE Format Functions
        ---------------------------------------------------------------------
        Function     Type Action
        ---------------------------------------------------------------------
        A            C    Allows only alphabetic characters.
        B            N    Displays numbers left-justified.
        C            N    Displays CR after positive numbers.
        D            D,N  Displays dates in SET DATE format.
        E            D,N  Displays dates with day and month inverted
                          independent of the current DATE SETting, numerics
                          with comma and period reverse (European style).
        K            ALL  Deletes default text if first key is not a cursor
                          key.
        R            C    Nontemplate characters are inserted in the display
                          but not saved in the variable.
        S<n>         C    Allows horizontal scrolling within a GET.  <n> is
                          an integer that specifies the width of the region.
        X            N    Displays DB after negative numbers.
        Z            N    Displays zero as blanks.
        (            N    Displays negative numbers in parentheses with
                          leading spaces.
        )            N    Displays negative numbers in parentheses without
                          leading spaces.
        !            C    Converts alphabetic character to uppercase.
        ---------------------------------------------------------------------

     ¦  Template string:  A PICTURE template string specifies
        formatting or validation rules on a character by character basis.
        The template string consists of a series of characters, some of which
        have special meanings (see the following table).  Each position in
        the template string corresponds to a position in the displayed GET
        value.  Characters in the template string that do not have assigned
        meanings are copied verbatim into the displayed GET value.  If you
        use the @R picture function, these characters are inserted between
        characters of the display value, and are automatically removed when
        the display value is reassigned to <idVar>; otherwise, they overwrite
        the corresponding characters of the display value and also affect the
        value assigned to <idVar>.  You may specify a template string alone
        or with a function string.  If you use both, the function string must
        precede the template string, and the two must be separated by a
        single space.

        GET PICTURE Template Symbols
        ---------------------------------------------------------------------
        Template     Action
        ---------------------------------------------------------------------
        A            Allows only alphabetic characters
        N            Allows only alphabetic and numeric characters
        X            Allows any character
        9            Allows digits for any data type including sign for
                     numerics
        #            Allows digits, signs and spaces for any data type
        L            Allows only T, F, Y or N
        Y            Allows only 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
        .            Displays a decimal point
        ,            Displays a comma
        ---------------------------------------------------------------------

? str( 324.6666334, 16, -1 ) // 325
? str( 324.6666334, -1 ) // 325
? str( 324.6666334, -1, 5 ) // 324,66663

Syntax
Str( <nNumber>   , ;
    [<nLength>]  , ;
    [<nDecimals>], ;
    [<lTrim>]      ) --> cString

Arguments
<nNumber> 
A numeric value to convert to a character string. 
<nLength> 
An optional numeric value specifying the length of the return string, including sign and decimal places. 
<nDecimals> 
This is an optional numeric value indicating the number of decimal places to return. 
<lTrim> 
This parameter defaults to .F. (false). When .T. (true) is passed, the returned string has no leading spaces. Return
The function returns <nNumber> formatted as a character string.