/*
 * $Id$
 */

/*
 * The following parts are Copyright of the individual authors.
 * www - http://www.harbour-project.org
 *
 * Copyright 1999 Jose Lalin <dezac@corevia.com>
 *    DESCEND() documentation
 *
 * Copyright 2000 Luiz Rafael Culik <culik@sl.conex.net>
 *    HB_OEMTOANSI() Documentation
 *    HB_ANSITOOEM() Documentation
 *    ISALPHA()   Documentation
 *    ISDIGIT()   Documentation
 *    ISUPPER()   Documentation
 *    ISLOWER()   Documentation
 *    LTRIM()     Documentation
 *    AT()        Documentation
 *    RAT()       Documentation  
 *    LEFT()      Documentation
 *    RIGHT()     Documentation
 *    SUBSTR()    Documentation  
 *    UPPER()     Documentation  
 *    LOWER()     Documentation
 *    ASC()       Documentation
 *    CHR()       Documentation
 * See doc/license.txt for licensing terms.
 *
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ISALPHA()
 *  $CATEGORY$
 *      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' ) ) 
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is CA-Clipper compliant   
 *  $PLATFORMS$
 *      All      
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      ISDIGIT(),ISLOWER(),ISUPPER(),LOWER(),UPPER()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ISDIGIT()
 *  $CATEGORY$
 *      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$
 *      QOUT( "isdigit( '12345' ) = ", isdigit( '12345' ) ) 
 *      QOUT( "isdigit( 'abcde' ) = ", isdigit( 'abcde' ) ) 
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is CA-Clipper compliant   
 *  $PLATFORMS$
 *      All   
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      ISALPHA(),ISLOWER(),ISUPPER(),LOWER(),UPPER()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ISUPPER()
 *  $CATEGORY$
 *      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 takes the caracter string <cString> and checks to
 *      see if the leftmost character is a uppercased letter.If so, the
 *      function will return a logical true (.T.);otherwise, it will
 *      return a logical false (.F.).   
 *  $EXAMPLES$
 *      QOUT( "isupper( 'Abcde' ) = ", isupper( 'Abcde' ) ) 
 *      QOUT( "isupper( 'abcde' ) = ", isupper( 'abcde' ) ) 
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is CA-Clipper compliant   
 *  $PLATFORMS$
 *      All    
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      ISALPHA(),ISLOWER(),ISDIGIT(),LOWER(),UPPER()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ISLOWER()
 *  $CATEGORY$
 *      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$
 *      QOUT( "islower( 'Abcde' ) = ", islower( 'Abcde' ) ) 
 *      QOUT( "islower( 'abcde' ) = ", islower( 'abcde' ) ) 
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is CA-Clipper compliant   
 *  $PLATFORMS$
 *      All   
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      ISALPHA(),ISDIGIT(),ISUPPER(),LOWER(),UPPER()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      LTRIM()
 *  $CATEGORY$
 *      Strings   
 *  $ONELINER$
 *      Removes leading spaces from a string 
 *  $SYNTAX$
 *      LTRIM(<cString>)   --> <cReturn>
 *  $ARGUMENTS$
 *      <cString>  Character expression with leading spaces   
 *  $RETURNS$
 *      <cReturn>  The same character expression with leading spaces removed   
 *  $DESCRIPTION$
 *      This function trims the leading space blank   
 *  $EXAMPLES$
 *      ? QOUT( LTRIM("HELLO     "))
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This functions is CA-CLIPPER compatible   
 *  $PLATFORMS$
 *      All  
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      TRIM(),RTRIM(),ALLTRIM()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      AT()
 *  $CATEGORY$
 *      Strings
 *  $ONELINER$
 *      Locates the position of a substring in a main string.
 *  $SYNTAX$
 *      AT(<cSearch>,<cString>) --> nPos
 *  $ARGUMENTS$
 *      <cSearch>  Substring to search for   
 *
 *      <cString>  Main string   
 *  $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.   
 *  $EXAMPLES$
 *      QOUT( "at( 'cde', 'abcdefgfedcba' ) = '" +;
 *      at( 'cde', 'abcsefgfedcba' ) + "'" )
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is CA-Clipper compatible.   
 *  $PLATFORMS$
 *      All   
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      RAT()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      RAT()
 *  $CATEGORY$
 *      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 value of the function will be 0.    
 *  $EXAMPLES$
 *      QOUT( "rat( 'cde', 'abcdefgfedcba' ) = '" +;
 *      rat( 'cde', 'abcsefgfedcba' ) + "'" )
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      Will not work with a search string > 64 KB on some platforms   
 *  $PLATFORMS$
 *      All   
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      AT(),SUBSTR(),RIGHT()
 *  $END$
 */

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

/*  $DOC$
 *  $FUNCNAME$
 *      RIGHT()
 *  $CATEGORY$
 *      Strings
 *  $ONELINER$
 *      Extract the rightmost substring of a character expression
 *  $SYNTAX$
 *      SUBSTR(<cString>,<nPos>) --> <cReturn>
 *  $ARGUMENTS$
 *      <cString> Character expression to be parsed   
 *
 *      <nPos>    Number of bytes to return beggining at the rightmost position   
 *  $RETURNS$
 *      <cReturn>  Substring of evaluation   
 *  $DESCRIPTION$
 *      This functions returns the rightmost <nPos> characters of <cString>.   
 *  $EXAMPLES$
 *      ? QOUT(RIGHT('HELLO HARBOUR',5))
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This functions is CA CLIPPER compatible   
 *  $PLATFORMS$
 *      All   
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      SUBSTR(),LEFT(),AT(),RAT()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      SUBSTR()
 *  $CATEGORY$
 *      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
 *      lenght 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>.   
 *  $EXAMPLES$
 *      FUNCTION MAIN()
 *      LOCAL X:=REPLICATE('ABCD',70000)
 *
 *      ? QOUT(SUBSTR(X,65519,200)
 *
 *      RETURN NIL
 *  </fixed>
 *  $TESTS$
 *      ? QOUT(SUBSTR('HELLO HARBOUR',5)
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This functions is CA CLIPPER compatible with the execption that
 *      CA CLIPPER will generate an error if the passed string is >65519 bytes
 *      and Harbour depends of plataform.   
 *  $PLATFORMS$
 *      All    
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *     LEFT(),AT(),RIGHT()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      STR()
 *  $CATEGORY$
 *      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"
 *      </fixed>
 *  $TESTS$
 *      see the regression test suit for comprehensive tests.
 *          </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      CA-Clipper compatible.   
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      STRZERO(),VAL()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      STRZERO()
 *  $CATEGORY$
 *      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.   
 *  $EXAMPLES$
 *      ? STRZERO( 10, 6, 2 ) // "010.00"
 *      ? STRZERO( -10, 8, 2 ) // "-0010.00"
 *  </fixed>
 *  $TESTS$
 *      see the regression test suit for comprehensive tests.
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      CA-Clipper compatible (it was not mentioned in the docs though).   
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      STR(),VAL()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      HB_VALTOSTR()
 *  $CATEGORY$
 *      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" )
 *  </fixed>
 *  $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."
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      HB_VALTOSTR() is a Harbour enhancement.   
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      STR(),VAL()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      LEN()
 *  $CATEGORY$
 *      Strings
 *  $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. If
 *      it is used with a multidimensional array it returns the size of the
 *      first dimension.   
 *  $EXAMPLES$
 *      ? Len( "Harbour" ) --> 7
 *      ? Len( { "One", "Two" } ) --> 2
 *  </fixed>
 *  $TESTS$
 *      function Test()
 *         LOCAL cName := ""
 *         ACCEPT "Enter your name: " TO cName
 *         ? Len( cName )
 *      return nil
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      LEN() is fully CA-Clipper compliant.   
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      EMPTY(),RTRIM(),LTRIM(),AADD(),ASIZE()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      EMPTY()
 *  $CATEGORY$
 *      Conversion
 *  $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" )
 *  </fixed>
 *  $TESTS$
 *      function Test()
 *         ? Empty( 1 )       --> .f.
 *         ? Empty( Date() )  --> .f.
 *         ? Empty( .f. )     --> .t.
 *      return nil
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      EMPTY() is fully CA-Clipper compliant.   
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      LEN()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      DESCEND()
 *  $CATEGORY$
 *      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" )
 /    </fixed>
 *  $TESTS$
 *      DATA->( DBSEEK( DESCEND( "SMITH" ) ) )
 *      will seek "SMITH" into a descending index.
 *      </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      DESCEND() is fully CA-Clipper compliant.   
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *       INDEX,SEEK
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      HB_ANSITOOEM()
 *  $CATEGORY$
 *      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")
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is a Harbour extension   
 *  $PLATFORMS$
 *      This functions work only on Windows Plataform   
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      HB_OEMTOANSI()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      HB_OEMTOANSI()
 *  $CATEGORY$
 *      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")
 *      </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is a Harbour extension   
 *  $PLATFORMS$
 *      This functions work only on Windows Plataform   
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      HB_ANSITOOEM()
 *  $END$
 */


/*  $DOC$
 *  $FUNCNAME$
 *      LOWER()
 *  $CATEGORY$
 *      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")
 *      ? Lower("Hello All")
 *      </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is CA-Clipper compatible   
 *  $PLATFORMS$
 *      ALL   
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      UPPER(),ISLOWER(),ISUPPER()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      UPPER()
 *  $CATEGORY$
 *      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")
 *      ? UPPER("Harbour")
 *  </fixed>
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is CA-Clipper compatible   
 *  $PLATFORMS$
 *      All   
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      LOWER(),ISUPPER(),ISLOWER()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      CHR()
 *  $CATEGORY$
 *      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$
 *      This function is Ca-Clipper compliant
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$   
 *      ASC(),INKEY()
 *  $END$
 */

/*  $DOC$
 *  $FUNCNAME$
 *      ASC()
 *  $CATEGORY$
 *      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("¹")
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      This function is Ca-Clipper compliant
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rtl
 *  $SEEALSO$
 *      CHR()
 *  $END$
 */

