harbour-core/harbour/doc/en/string.txt

/*
 * $Id$
 */

/*
 * The following parts are Copyright of the individual authors.
 * www - http://harbour-project.org
 *
 * Copyright 1999 Jose Lalin <dezac@corevia.com>
 *    Documentation for: DESCEND()
 *
 * Copyright 2000 Luiz Rafael Culik <culik@sl.conex.net>
 *    Documentation for: HB_OEMTOANSI(), HB_ANSITOOEM(), ISALPHA(), ISDIGIT(),
 *                       ISUPPER(), ISLOWER(), LTRIM(), AT(), RAT(), LEFT(),
 *                       RIGHT(), SUBSTR(), UPPER(), LOWER(), ASC(), CHR(),
 *                       PADC(), PADL(), PADR(), ALLTRIM(), TRIM(), RTRIM(),
 *                       SPACE(), REPLICATE(), VAL(), TRANSFORM(), STRTRAN()
 *
 * See COPYING for licensing terms.
 *
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      ISALPHA()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Checks if leftmost character in a string is an alphabetic character
 *  $SYNTAX$
 *      ISALPHA( <cString> ) --> lAlpha
 *  $ARGUMENTS$
 *      <cString> Any character string
 *  $RETURNS$
 *      lAlpha Logical true (.T.) or false (.F.).
 *  $DESCRIPTION$
 *      This function return a logical true (.T.) if the first character
 *      in <cString> is an alphabetic character. If not, the function will
 *      return a logical false (.F.).
 *  $EXAMPLES$
 *      QOUT( "isalpha( 'hello' ) = ", isalpha( 'hello' ) )
 *      QOUT( "isalpha( '12345' ) = ", isalpha( '12345' ) )
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      ISDIGIT(),ISLOWER(),ISUPPER(),LOWER(),UPPER()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      ISDIGIT()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Checks if leftmost character is a digit character
 *  $SYNTAX$
 *      ISDIGIT( <cString> ) --> lDigit
 *  $ARGUMENTS$
 *      <cString> Any character string
 *  $RETURNS$
 *      lDigit Logical true (.T.) or false (.F.).
 *  $DESCRIPTION$
 *      This function takes the caracter string <cString> and checks to
 *      see if the leftmost character is a digit, from 1 to 9. If so, the
 *      function will return a logical true (.T.); otherwise, it will
 *      return a logical false (.F.).
 *  $EXAMPLES$
 *      ? ISDIGIT( '12345' )      // .T.
 *      ? ISDIGIT( 'abcde' )      // .F.
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      ISALPHA(),ISLOWER(),ISUPPER(),LOWER(),UPPER()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      ISUPPER()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Checks if leftmost character is an uppercased letter.
 *  $SYNTAX$
 *      ISUPPER( <cString> ) --> lUpper
 *  $ARGUMENTS$
 *      <cString> Any character string
 *  $RETURNS$
 *      lUpper Logical true (.T.) or false (.F.).
 *  $DESCRIPTION$
 *      This function checks to see if the leftmost character
 *      if <cString> is a uppercased letter. If so, the
 *      function will return a logical true (.T.); otherwise, it will
 *      return a logical false (.F.).
 *  $EXAMPLES$
 *      ? ISUPPER( 'Abcde' )    // .T.
 *      ? ISUPPER( 'abcde' )    // .F.
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      ISALPHA(),ISLOWER(),ISDIGIT(),LOWER(),UPPER()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      ISLOWER()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Checks if leftmost character is an lowercased letter.
 *  $SYNTAX$
 *      ISLOWER( <cString> ) --> lLower
 *  $ARGUMENTS$
 *      <cString> Any character string
 *  $RETURNS$
 *      lLower Logical true (.T.) or false (.F.).
 *  $DESCRIPTION$
 *      This function takes the caracter string <cString> and checks to
 *      see if the leftmost character is a lowercased letter. If so, the
 *      function will return a logical true (.T.); otherwise, it will
 *      return a logical false (.F.).
 *  $EXAMPLES$
 *      ? islower( 'ABCde' )      // .F.
 *      ? islower( 'aBCde' )      // .T.
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      ISALPHA(),ISDIGIT(),ISUPPER(),LOWER(),UPPER()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      LTRIM()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Removes leading spaces from a string
 *  $SYNTAX$
 *      LTRIM( <cString> ) --> cReturn
 *  $ARGUMENTS$
 *      <cString>  Character expression with leading spaces
 *  $RETURNS$
 *      LTRIM() returns a copy of the original string with leading spaces
 *      removed.
 *  $DESCRIPTION$
 *      This function trims the leading space blank
 *  $EXAMPLES$
 *      ? LTRIM( "HELLO     " )
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      TRIM(),RTRIM(),ALLTRIM()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      AT()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Locates the position of a substring in a main string.
 *  $SYNTAX$
 *      AT( <cSearch>, <cString>, [<nStart>], [<nEnd>] ) --> nPos
 *  $ARGUMENTS$
 *      <cSearch> Substring to search for
 *
 *      <cString> Main string
 *
 *      <nStart> First position to search in cString, by default 1
 *
 *      <nEnd> End posistion to search, by default cString length
 *  $RETURNS$
 *      AT() return the starting position of the first occurrence of the
 *      substring in the main string
 *  $DESCRIPTION$
 *      This function searches the string <cString> for the characters in
 *      the first string <cSearch>. If the substring is not contained within
 *      the second expression, the function will return 0. The third and fourth
 *      parameters lets you indicate a starting and end offset to search in.
 *  $EXAMPLES$
 *      QOUT( "at( 'cde', 'abcdefgfedcba' ) = '" +;
 *      at( 'cde', 'abcsefgfedcba' ) + "'" )
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is sensitive to HB_CLP_STRICT settings during the
 *      compilation of src/rtl/at.c
 *
 *      <nStart> and <nEnd> are Harbour extensions and do not exist if
 *      HB_CLP_STRICT is defined. In that case, the whole string is searched.
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      RAT()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      RAT()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Searches for a substring from the right side of a string.
 *  $SYNTAX$
 *      RAT( <cSearch>, <cString> ) --> nPos
 *  $ARGUMENTS$
 *      <cSearch> Substring to search for
 *
 *      <cString> Main string
 *  $RETURNS$
 *      RAT() return the location of beginnig position.
 *  $DESCRIPTION$
 *      This function searches througt <cString> for the first existence
 *      of <cSearch>. The search operation is performed from the right side
 *      of <cString> to the left. If the function is unable to find any
 *      occurence of <cSearch> in <cString>, the return value is 0.
 *  $EXAMPLES$
 *      QOUT( "rat( 'cde', 'abcdefgfedcba' ) = '" +;
 *      rat( 'cde', 'abcsefgfedcba' ) + "'" )
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All(64K)
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      AT(), SUBSTR(), RIGHT()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      LEFT()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Extract the leftmost substring of a character expression
 *  $SYNTAX$
 *      LEFT( <cString>, <nLen> ) --> cReturn
 *  $ARGUMENTS$
 *      <cString> Main character to be parsed
 *
 *      <nLen> Number of bytes to return beggining at the leftmost position
 *  $RETURNS$
 *      <cReturn>  Substring of evaluation
 *  $DESCRIPTION$
 *      This functions returns the leftmost <nLen> characters of <cString>.
 *      It is equivalent to the following expression:
 *
 *      SUBSTR( <cString>, 1, <nLen> )
 *  $EXAMPLES$
 *      ? LEFT( 'HELLO HARBOUR', 5 )    // HELLO
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      SUBSTR(),RIGHT(),AT(),RAT()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      RIGHT()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Extract the rightmost substring of a character expression
 *  $SYNTAX$
 *      RIGHT( <cString>, <nLen> ) --> cReturn
 *  $ARGUMENTS$
 *      <cString> Character expression to be parsed
 *
 *      <nLen> Number of bytes to return beggining at the rightmost position
 *  $RETURNS$
 *      <cReturn>  Substring of evaluation
 *  $DESCRIPTION$
 *      This functions returns the rightmost <nLen> characters of <cString>.
 *      It is equivalent to the following expressions:
 *
 *      SUBSTR( <cString>,  - <nLen> )
 *
 *      SUBSTR( <cString>, LEN( <cString> ) - <nLen> + 1, <nLen> )
 *  $EXAMPLES$
 *      ? RIGHT( 'HELLO HARBOUR', 5 )     // RBOUR
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      SUBSTR(),LEFT(),AT(),RAT()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      SUBSTR()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Returns a substring from a main string
 *  $SYNTAX$
 *      SUBSTR( <cString>, <nStart>, [<nLen>] ) --> cReturn
 *  $ARGUMENTS$
 *      <cString> Character expression to be parsed
 *
 *      <nStart> Start position
 *
 *      <nLen> Number of characters to return
 *  $RETURNS$
 *      <cReturn> Substring of evaluation
 *  $DESCRIPTION$
 *      This functions returns a character string formed from <cString>,
 *      starting at the position of <nStart> and continuing on for a
 *      length of <nLen> characters. If <nLen> is not specified, the value
 *      will be all remaining characters from the position of <nStart>.

 *      The value of <nStart> may be negative. If it is, the direction of
 *      operation is reversed from a default of left-to-right to right-to-left
 *      for the number of characters specified in <nStart>. If the number of
 *      characters from <nStart> to the end of the string is less than <nLen>
 *      the rest are ignored.
 *  $EXAMPLES$
 *      ? SUBSTR( 'HELLO HARBOUR' , 7, 4 )      // HARB
 *      ? SUBSTR( 'HELLO HARBOUR' ,-3, 3 )      // OUR
 *      ? SUBSTR( 'HELLO HARBOUR' , 7    )      // HARBOUR
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All(64K)
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *     LEFT(),AT(),RIGHT()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      STR()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Convert a numeric expression to a character string.
 *  $SYNTAX$
 *      STR( <nNumber>, [<nLength>], [<nDecimals>] ) --> cNumber
 *  $ARGUMENTS$
 *      <nNumber> is the numeric expression to be converted to a character
 *      string.
 *
 *      <nLength> is the length of the character string to return, including
 *      decimal digits, decimal point, and sign.
 *
 *      <nDecimals> is the number of decimal places to return.
 *  $RETURNS$
 *      STR() returns <nNumber> formatted as a character string.  If the
 *      optional length and decimal arguments are not specified, STR()
 *      returns the character string according to the following rules:
 *
 *      Results of STR() with No Optional Arguments
 *
 *  <table>
 *      Expression               Return Value Length
 *
 *      Field Variable           Field length plus decimals
 *      Expressions/constants    Minimum of 10 digits plus decimals
 *      VAL()                    Minimum of 3 digits
 *      MONTH()/DAY()            3 digits
 *      YEAR()                   5 digits
 *      RECNO()                  7 digits
 *      </table>
 *  $DESCRIPTION$
 *      STR() is a numeric conversion function that converts numeric values
 *      to character strings. It is commonly used to concatenate numeric
 *      values to character strings. STR() has applications displaying
 *      numbers, creating codes such as part numbers from numeric values,
 *      and creating index keys that combine numeric and character data.
 *
 *      STR() is like TRANSFORM(), which formats numeric values as character
 *      strings using a mask instead of length and decimal specifications.
 *
 *      The inverse of STR() is VAL(), which converts character numbers to
 *      numerics.
 *
 *      *  If <nLength> is less than the number of whole number digits in
 *         <nNumber>, STR() returns asterisks instead of the number.
 *
 *      *  If <nLength> is less than the number of decimal digits
 *         required for the decimal portion of the returned string, Harbour
 *         rounds the number to the available number of decimal places.
 *
 *      *  If <nLength> is specified but <nDecimals> is omitted (no
 *         decimal places), the return value is rounded to an integer.
 *  $EXAMPLES$
 *      ? STR( 10, 6, 2 ) // " 10.00"
 *      ? STR( -10, 8, 2 ) // "  -10.00"
 *  $TESTS$
 *      See the regression test suit for comprehensive tests.
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      STRZERO(),TRANSFORM(),VAL()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      STRZERO()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Convert a numeric expression to a character string, zero padded.
 *  $SYNTAX$
 *      STRZERO( <nNumber>, [<nLength>], [<nDecimals>] ) --> cNumber
 *  $ARGUMENTS$
 *      <nNumber> is the numeric expression to be converted to a character
 *      string.
 *
 *      <nLength> is the length of the character string to return, including
 *      decimal digits, decimal point, and sign.
 *
 *      <nDecimals> is the number of decimal places to return.
 *  $RETURNS$
 *      STRZERO() returns <nNumber> formatted as a character string.  If the
 *      optional length and decimal arguments are not specified, STRZERO()
 *      returns the character string according to the following rules:
 *
 *      Results of STRZERO() with No Optional Arguments
 *
 *      <table>
 *      Expression               Return Value Length
 *
 *      Field Variable           Field length plus decimals
 *      Expressions/constants    Minimum of 10 digits plus decimals
 *      VAL()                    Minimum of 3 digits
 *      MONTH()/DAY()            3 digits
 *      YEAR()                   5 digits
 *      RECNO()                  7 digits
 *      </table>
 *  $DESCRIPTION$
 *      STRZERO() is a numeric conversion function that converts numeric
 *      values to character strings. It is commonly used to concatenate
 *      numeric values to character strings. STRZERO() has applications
 *      displaying numbers, creating codes such as part numbers from numeric
 *      values, and creating index keys that combine numeric and character
 *      data.
 *
 *      STRZERO() is like TRANSFORM(), which formats numeric values as
 *      character strings using a mask instead of length and decimal
 *      specifications.
 *
 *      The inverse of STRZERO() is VAL(), which converts character numbers
 *      to numerics.
 *
 *      *  If <nLength> is less than the number of whole number digits in
 *         <nNumber>, STR() returns asterisks instead of the number.
 *
 *      *  If <nLength> is less than the number of decimal digits
 *         required for the decimal portion of the returned string, Harbour
 *         rounds the number to the available number of decimal places.
 *
 *      *  If <nLength> is specified but <nDecimals> is omitted (no
 *         decimal places), the return value is rounded to an integer.
 *
 *      The STRZERO() function was part of the CA-Cl*pper samples.
 *  $EXAMPLES$
 *      ? STRZERO( 10, 6, 2 ) // "010.00"
 *      ? STRZERO( -10, 8, 2 ) // "-0010.00"
 *  $TESTS$
 *      see the regression test suit for comprehensive tests.
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      STR()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      HB_VALTOSTR()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Converts any scalar type to a string.
 *  $SYNTAX$
 *      HB_VALTOSTR( <xValue> ) --> cString
 *  $ARGUMENTS$
 *      <xValue> is any scalar argument.
 *  $RETURNS$
 *      <cString> A string representation of <xValue> using default
 *      conversions.
 *  $DESCRIPTION$
 *      HB_VALTOSTR can be used to convert any scalar value to a string.
 *  $EXAMPLES$
 *      ? HB_VALTOSTR( 4 )
 *      ? HB_VALTOSTR( "String" )
 *  $TESTS$
 *      ? HB_VALTOSTR( 4 ) == "         4"
 *      ? HB_VALTOSTR( 4.0 / 2 ) == "         2.00"
 *      ? HB_VALTOSTR( "String" ) == "String"
 *      ? HB_VALTOSTR( CTOD( "01/01/2001" ) ) == "01/01/01"
 *      ? HB_VALTOSTR( NIL ) == "NIL"
 *      ? HB_VALTOSTR( .F. ) == ".F."
 *      ? HB_VALTOSTR( .T. ) == ".T."
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      H
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      STR()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      LEN()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Variable management
 *  $ONELINER$
 *      Returns size of a string or size of an array.
 *  $SYNTAX$
 *      LEN( <cString> | <aArray> ) --> <nLength>
 *  $ARGUMENTS$
 *      <acString> is a character string or the array to check.
 *  $RETURNS$
 *      The length of the string or the number of elements that contains
 *      an array.
 *  $DESCRIPTION$
 *      This function returns the string length or the size of an array or the
 *      size of a hash table. If it is used with a multidimensional array it
 *      returns the size of the first dimension.
 *  $EXAMPLES$
 *      ? LEN( "Harbour" )           // 7
 *      ? LEN( { "One", "Two" } )    // 2
 *  $TESTS$
 *      function Test()
 *         LOCAL cName := ""
 *         ACCEPT "Enter your name: " TO cName
 *         ? LEN( cName )
 *      return nil
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      EMPTY(),RTRIM(),LTRIM(),AADD(),ASIZE()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      EMPTY()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Variable management
 *  $ONELINER$
 *      Checks if the passed argument is empty.
 *  $SYNTAX$
 *      EMPTY( <xExp> ) --> lIsEmpty
 *  $ARGUMENTS$
 *      <xExp> is any valid expression.
 *  $RETURNS$
 *      A logical value. It is true (.T.) if the passed argument is empty
 *      otherwise it is false (.F.).
 *  $DESCRIPTION$
 *      This function checks if an expression has empty value and returns a
 *      logical indicating whether it the expression is empty or not.
 *  $EXAMPLES$
 *      ? EMPTY( "I'm not empty" )    // .F.
 *  $TESTS$
 *      FUNCTION Test()
 *         ? EMPTY( NIL )             // .T.
 *         ? EMPTY( 0 )               // .T.
 *         ? EMPTY( .F. )             // .T.
 *         ? EMPTY( "" )              // .T.
 *         ? EMPTY( 1 )               // .F.
 *         ? EMPTY( .T. )             // .F.
 *         ? EMPTY( "smile" )         // .F.
 *         ? EMPTY( Date() )          // .F.
 *      RETURN NIL
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      LEN()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      DESCEND()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Conversion
 *  $ONELINER$
 *      Inverts an expression of string, logical, date or numeric type.
 *  $SYNTAX$
 *      DESCEND( <xExp> ) --> xExpInverted
 *  $ARGUMENTS$
 *      <xExp> is any valid expression.
 *  $RETURNS$
 *      Inverted value of the same type as passed.
 *  $DESCRIPTION$
 *      This function converts an expression in his inverted form. It is
 *      useful to build descending indexes.
 *  $EXAMPLES$
 *      // Seek for Smith in a descending index
 *      SEEK DESCEND( "SMITH" )
 *  $TESTS$
 *      DATA->( DBSEEK( DESCEND( "SMITH" ) ) )
 *      will seek "SMITH" into a descending index.
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *       INDEX, SEEK
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      HB_ANSITOOEM()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Convert a windows Character to a Dos based character
 *  $SYNTAX$
 *      HB_ANSITOOEM( <cString> ) --> cDosString
 *  $ARGUMENTS$
 *      <cString> Windows ansi string to convert to DOS oem String
 *  $RETURNS$
 *      <cDosString> Dos based  string
 *  $DESCRIPTION$
 *      This function converts each character in <cString> to the
 *      corresponding character in the MS-DOS (OEM) character set. The
 *      character expression <cString> should contain characters from the
 *      ANSI character set. If a character in <cString> doesn't have a
 *      MS-DOS equivalent, the character is converted to a similar MS-DOS
 *      character.
 *  $EXAMPLES$
 *      ? HB_OEMTOANSI( "Harbour" )
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      H
 *  $PLATFORMS$
 *      Win
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      HB_OEMTOANSI()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      HB_OEMTOANSI()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Convert a DOS(OEM) Character to a WINDOWS (ANSI) based character
 *  $SYNTAX$
 *      HB_OEMTOANSI( <cString> )  --> cDosString
 *  $ARGUMENTS$
 *      <cString>  DOS (OEM)  string to convert to WINDOWS (ANSI) String
 *  $RETURNS$
 *      <cDosString> WINDOWS based  string
 *  $DESCRIPTION$
 *      This function converts each character in <cString> to the
 *      corresponding character in the Windows (ANSI) character set. The
 *      character expression <cString> should contain characters from the
 *      OEM character set. If a character in <cString> doesn't have a ANSI
 *      equivalent, the character is remais the same.
 *  $EXAMPLES$
 *      ? HB_OEMTOANSI( "Harbour" )
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      H
 *  $PLATFORMS$
 *      Win
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      HB_ANSITOOEM()
 *  $END$
 */


/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      LOWER()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Universally lowercases a character string expression.
 *  $SYNTAX$
 *      LOWER( <cString> ) --> cLowerString
 *  $ARGUMENTS$
 *      <cString> Any character expression.
 *  $RETURNS$
 *      <cLowerString> Lowercased value of <cString>
 *  $DESCRIPTION$
 *      This function converts any character expression passes as <cString>
 *      to its lowercased representation.Any nonalphabetic character withing
 *      <cString> will remain unchanged.
 *  $EXAMPLES$
 *      ? LOWER( "HARBOUR" )      // harbour
 *      ? LOWER( "Hello All" )    // hello all
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      UPPER(),ISLOWER(),ISUPPER()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      UPPER()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Converts a character expression to uppercase format
 *  $SYNTAX$
 *      UPPER( <cString> ) --> cUpperString
 *  $ARGUMENTS$
 *      <cString> Any character expression.
 *  $RETURNS$
 *      <cUpperString> Uppercased value of <cString>
 *  $DESCRIPTION$
 *      This function converts all alpha characters in <cString> to upper
 *      case values and returns that formatted character expression.
 *  $EXAMPLES$
 *      ? UPPER( "harbour" )       // HARBOUR
 *      ? UPPER( "Harbour" )       // HARBOUR
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      LOWER(),ISUPPER(),ISLOWER()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      CHR()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Converts an ASCII value to it character value
 *  $SYNTAX$
 *      CHR( <nAsciiNum> )  --> cReturn
 *  $ARGUMENTS$
 *      <nAsciiNum> Any ASCII character code.
 *  $RETURNS$
 *      <cReturn> Character expression of that ASCII value
 *  $DESCRIPTION$
 *      This function returns the ASCII character code for <nAsciiNum>. The
 *      number expressed must be an interger value within the range of 0 to
 *      255 inclusive. The CHR() function will send the character returned
 *      to whatever device is presently set.
 *
 *      The CHR() function may be used for printing special codes as well
 *      as normal and graphics character codes.
 *  $EXAMPLES$
 *      ? CHR( 32 )
 *      ? chr( 215 )
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      ASC(), INKEY()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      ASC()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Returns the ASCII value of a character
 *  $SYNTAX$
 *      ASC( <cCharacter> ) --> nAscNumber
 *  $ARGUMENTS$
 *      <cCharacter> Any character expression
 *  $RETURNS$
 *      <nAscNumber> ASCII value
 *  $DESCRIPTION$
 *      This function return the ASCII value of the leftmost character of
 *      any character expression passed as <cCharacter>.
 *  $EXAMPLES$
 *      ? ASC( "A" )
 *      ? ASC( "<22>" )
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      CHR()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      PADC()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Centers an expression for a given width
 *  $SYNTAX$
 *      PADC( <xVal>, <nWidth>, <cFill> )  --> cString
 *  $ARGUMENTS$
 *      <xVal> A Number, Character or Date value to pad
 *
 *      <nWidth> Width of output string
 *
 *      <cFill> Character to fill in the string
 *  $RETURNS$
 *      <cString> The Center string of <xVal>
 *  $DESCRIPTION$
 *      This function takes an date, number or character expression <xVal>
 *      and attempt to center the expression within a string of a given width
 *      expressed as <nWidth>. The default character used to pad either side
 *      of <xVal> will be a blank space. This character may be explicitly
 *      specified the value of <cFill>.
 *
 *      If the length of <xVal> is longer then <nWidth>, this function will
 *      truncate the string <xVal> from the leftmost side to the length of
 *      <nWidth>.
 *  $EXAMPLES$
 *      ? PADC( 'Harbour',20 )
 *      ? PADC( 34.5142, 20 )
 *      ? PADC( Date(), 35 )
 *  $TESTS$
 *      See Examples
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      ALLTRIM(),PADL(),PADR()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      PADL()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Left-justifies an expression for a given width
 *  $SYNTAX$
 *      PADL( <xVal>, <nWidth>, <cFill> )  --> cString
 *  $ARGUMENTS$
 *      <xVal> An number,Character or date to pad
 *
 *      <nWidth> Width of output string
 *
 *      <cFill> Character to fill in the string
 *  $RETURNS$
 *      <cString> The left-justifies string of <xVal>
 *  $DESCRIPTION$
 *      This function takes an date,number,or character expression <xVal>
 *      and attempt to left-justify it within a string of a given width
 *      expressed as <nWidth>. The default character used to pad left side
 *      of <xVal> will be an blank space; however, this character may be
 *      explicitly specified the value of <cFill>.
 *
 *      If the length of <xVal> is longer then <nWidth>, this function will
 *      truncate the string <xVal> from the leftmost side to the length of
 *      <nWidth>.
 *  $EXAMPLES$
 *      ? PADL( 'Harbour', 20 )
 *      ? PADL( 34.5142, 20 )
 *      ? PADL( Date(), 35 )
 *  $TESTS$
 *      See examples
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      ALLTRIM(),PADC(),PADR()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      PADR()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Right-justifies an expression for a given width
 *  $SYNTAX$
 *      PADR( <xVal>, <nWidth>, <cFill> ) --> cString
 *  $ARGUMENTS$
 *      <xVal> A Number, Character or Date value to pad
 *
 *      <nWidth> Width of output string
 *
 *      <cFill> Character to fill in the string
 *  $RETURNS$
 *      <cString> The right-justifies string of <xVal>
 *  $DESCRIPTION$
 *      This function takes an date,number,or character expression <xVal>
 *      and attempt to right-justify it within a string of a given width
 *      expressed as <nWidth>. The default character used to pad right side
 *      of <xVal> will be an blank space; however, this character may be
 *      explicitly specified the value of <cFill>.
 *
 *      If the length of <xVal> is longer then <nWidth>, this function will
 *      truncate the string <xVal> from the leftmost side to the length of
 *      <nWidth>.
 *  $EXAMPLES$
 *      ? PADR( 'Harbour', 20 )
 *      ? PADR( 34.5142, 20 )
 *      ? PADR( Date(), 35 )
 *  $TESTS$
 *      See examples
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      ALLTRIM(),PADC(),PADL()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      ALLTRIM()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Removes leading and trailing blank spaces from a string
 *  $SYNTAX$
 *      ALLTRIM( <cString> ) --> cExpression
 *  $ARGUMENTS$
 *      <cString> Any character string
 *  $RETURNS$
 *      <cExpression> An string will all blank spaces removed from <cString>
 *  $DESCRIPTION$
 *      This function returns the string <cExpression> will all leading and
 *      trailing blank spaces removed.
 *  $EXAMPLES$
 *      ? ALLTRIM( "HELLO HARBOUR" )
 *      ? ALLTRIM( "     HELLO HARBOUR" )
 *      ? ALLTRIM( "HELLO HARBOUR     " )
 *      ? ALLTRIM( "     HELLO HARBOUR     " )
 *  $TESTS$
 *      See Examples
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      LTRIM(),RTRIM(),TRIM()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      RTRIM()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Remove trailing spaces from a string.
 *  $SYNTAX$
 *      RTRIM( <cExpression> ) --> cString
 *  $ARGUMENTS$
 *      <cExpression> Any character expression
 *  $RETURNS$
 *      <cString> A formated string with out any blank spaced.
 *  $DESCRIPTION$
 *      This function returns the value of <cString> with any trailing blank
 *      removed.
 *
 *      This function is indentical to RTRIM() and the opposite of LTRIM().
 *      Together with LTRIM(), this function equated to the ALLTRIM()
 *      function.
 *  $EXAMPLES$
 *      ? RTRIM( "HELLO" )              //  "HELLO"
 *      ? RTRIM( "" )                   //  ""
 *      ? RTRIM( "UA   " )              //  "UA"
 *      ? RTRIM( "   UA" )              //  "   UA"
 *  $TESTS$
 *      See Examples
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      ALLTRIM(),LTRIM(),TRIM()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      TRIM()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Remove trailing spaces from a string.
 *  $SYNTAX$
 *      TRIM( <cExpression> )   --> cString
 *  $ARGUMENTS$
 *      <cExpression> Any character expression
 *  $RETURNS$
 *      <cString> A formated string with out any blank spaced.
 *  $DESCRIPTION$
 *      This function returns the value of <cString> with any trailing blank
 *      removed.
 *
 *      This function is indentical to RTRIM() and the opposite of LTRIM().
 *      Together with LTRIM(), this function equated to the ALLTRIM()
 *      function.
 *  $EXAMPLES$
 *      ? TRIM( "HELLO" )     //  "HELLO"
 *      ? TRIM( "" )          //   ""
 *      ? TRIM( "UA   " )     //   "UA"
 *      ? TRIM( "   UA" )     //   "   UA"
 *  $TESTS$
 *      See Examples
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      RTRIM(),LTRIM(),ALLTRIM()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      REPLICATE()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Repeats a single character expression
 *  $SYNTAX$
 *      REPLICATE( <cString>, <nSize> )  --> cReplicateString
 *  $ARGUMENTS$
 *      <cString> Character string to be replicated
 *
 *      <nSize> Number of times to replicate <cString>
 *  $RETURNS$
 *      <cReplicateString> A character expression containg the <cString>
 *      fill character.
 *  $DESCRIPTION$
 *      This function returns a string composed of <nSize> repetitions of
 *      <cString>. The length of the character string returned by this
 *      function is limited to the memory avaliable.
 *
 *      A value of 0 for <nSize> will return a NULL string.
 *  $EXAMPLES$
 *      ? REPLICATE( 'a', 10 )      // aaaaaaaaaa
 *      ? REPLICATE( 'b', 100000 )
 *  $TESTS$
 *      See Examples
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All(64K)
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      SPACE(),PADC(),PADL(),PADR()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      SPACE()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Returns a string of blank spaces
 *  $SYNTAX$
 *      SPACE( <nSize> ) --> cString
 *  $ARGUMENTS$
 *      <nSize> The length of the string
 *  $RETURNS$
 *      <cString> A string containing blank spaces
 *  $DESCRIPTION$
 *      This function returns a string consisting of <nSize> blank spaces.
 *      If the value of <nSize> is 0, a NULL string ( "" ) will be returned.
 *
 *      This function is useful to declare the length of a character memory
 *      variable.
 *  $EXAMPLES$
 *      FUNC MAIN
 *      LOCAL cBigString
 *      LOCAL cFirst
 *      LOCAL cString := Space(20)   // Create an character memory variable
 *                                   // with length 20
 *      ? len(cString)      // 20
 *      cBigString:=space(100000)    // create a memory variable with 100000
 *                                   // blank spaces
 *      ?  len(cBigString)
 *      Use Tests New
 *      cFirst:= makeempty(1)
 *      ? len(cFirst)
 *      Return Nil
 *
 *      Function MakeEmpty(xField)
 *      LOCAL nRecord
 *      LOCAL xRetValue
 *
 *      If !empty(alias())
 *          nRecord:=recno()
 *          dbgoto(0)
 *          if valtype(xField)=="C"
 *              xField:= ascan(dbstruct(),{|aFields| aFields[1]==upper(xfield)})
 *          else
 *              default xField to 0
 *              if xField < 1 .or. xField>fcount()
 *                  xfield:=0
 *              endif
 *          endif
 *          if !(xfield ==0)
 *              xRetvalue:=fieldget(xfield)
 *          endif
 *          dbgoto(nrecord)
 *      endif
 *      return xRetvalue
 *  $TESTS$
 *      See examples
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All(64K)
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      PADC(),PADL(),PADR(),REPLICATE()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      VAL()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Convert a number from a character type to numeric
 *  $SYNTAX$
 *      VAL( <cNumber> ) --> nNumber
 *  $ARGUMENTS$
 *      <cNumber> Any valid character string of numbers.
 *  $RETURNS$
 *      <nNumber> The numeric value of <cNumber>
 *  $DESCRIPTION$
 *      This function converts any number previosly defined as an character
 *      expression <cNumber> into a numeric expression.
 *
 *      This functions is the oppose of the STR() function.
 *  $EXAMPLES$
 *      ? VAL( '31421' ) // 31421
 *  $TESTS$
 *      See regression test
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      STR(),TRANSFORM()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      STRTRAN()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Translate substring value with a main string
 *  $SYNTAX$
 *      STRTRAN( <cString>, <cLocString>, [<cRepString>], [<nPos>],
 *               [<nOccurences>] ) --> cReturn
 *  $ARGUMENTS$
 *      <cString>     The main string to search
 *
 *      <cLocString>  The string to locate in the main string
 *
 *      <cRepString>  The string to replace the <cLocString>
 *
 *      <nPos>        The first occurence to be replaced
 *
 *      <nOccurences> Number of occurence to replace
 *  $RETURNS$
 *      <cReturn>  Formated string
 *  $DESCRIPTION$
 *      This function searches for any occurence of <cLocString> in <cString>
 *      and replacesit with <cRepString>. If <cRepString> is not specified, a
 *      NULL byte will replace <cLocString>.
 *
 *      If <nPos> is used, its value defines the first occurence to be
 *      replaced. The default value is 1. Additionally, if used, the value of
 *      <nOccurences> tell the function how many occurrences of <cLocString>
 *      in <cString> are to the replaced. The default of <nOccurences> is
 *      all occurrences.
 *  $EXAMPLES$
 *      ? STRTRAN( "Harbour  Power", "  ", " " )   // Harbour Power
 *               // Harbour Power The future  of  xBase
 *      ? STRTRAN( "Harbour  Power  The Future  of  xBase", "  ", " " ,, 2 )
 *  $TESTS$
 *      See regression test
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All(64K)
 *  $FILES$
 *      Libraty is rtl
 *  $SEEALSO$
 *      SUBSTR(),AT()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      TRANSFORM()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Strings
 *  $ONELINER$
 *      Formats a value based on a specific picture template.
 *  $SYNTAX$
 *      TRANSFORM( <xExpression>, <cTemplate> )  --> cFormated
 *  $ARGUMENTS$
 *      <xExpression> Any expression to be formated.
 *
 *      <cTemplate> Character string with picture template
 *  $RETURNS$
 *      <cFormated> Formatted expression in character format
 *  $DESCRIPTION$
 *      This function returns <xExpression> in the format of the picture
 *      expression passed to the function as <cTemplate>.
 *
 *      Their are two components that can make up <cTemplate> : a function
 *      string and a template string.Function strings are those functions
 *      that globally tell what the format of <xExpression> should be. These
 *      functions are represented by a single character precede by the
 *      @ symbol.
 *
 *      There are a couple of rules to follow when using function strings
 *      and template strings:
 *
 *       - First, a single space must fall between the function template
 *         and the template string if they are used in conjunction with
 *         one another.
 *
 *       - Second, if both components make up the value of <cTemplate>, the
 *         function string must precede the template string. Otherwise, the
 *         function string may appear with out the template string and
 *         vice versa.
 *
 *      The table below shows the possible function strings avaliable with
 *      the TRANSFORM() function.
 *
 *      <table>
 *      @B   Left justify the string within the format.
 *      @C   Issue a CR after format is numbers are positive.
 *      @D   Put dates in SET DATE format.
 *      @E   Put dates in BRITISH format.
 *      @L   Make a zero padded string out of the number.
 *      @R   Insert nontemplate characters.
 *      @X   Issue a DB after format is numbers are negative.
 *      @Z   Display any zero as blank spaces.
 *      @(   Quotes around negative numbers
 *      @!   Convert alpha characters to uppercased format.
 *      </table>
 *
 *      The second part of <cTemplate> consists of the format string.Each
 *      character in the string may be formated based on using the follow
 *      characters as template markers for the string.
 *
 *      <table>
 *      A,N,X,9,#   Any data type
 *      L           Shows logical as "T" or "F"
 *      Y           Shows logical as "Y" or "N"
 *      !           Convert to uppercase
 *      $           Dolar sing in place of leading spaces in numeric expression
 *      *           Asterisks in place of leading spaces in numeric expression
 *      ,           Commas position
 *      .           Decimal point position
 *      </table>
 *  $EXAMPLES$
 *      LOCAL cString := 'This is harbour'
 *      LOCAL nNumber := 9923.34
 *      LOCAL nNumber1 := -95842.00
 *      LOCAL lValue := .T.
 *      LOCAL dDate := DATE()
 *      ? 'working with String'
 *      ? "Current String is", cString
 *      ? "All uppercased", TRANSFORM( cString, "@!" )
 *      ? "Date is", ddate
 *      ? "Date is ", TRANSFORM( ddate, "@D" )
 *      ? TRANSFORM( nNumber, "@L 99999999" )  //  "009923.34"
 *      ? TRANSFORM( 0      , "@L 9999"     )  //  "0000"
 *  $TESTS$
 *      See regression Test
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      The @L function template is a FoxPro/Xbase++ Extension
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      @...SAY,DEVOUTPICT()
 *  $END$
 */