/* * $Id$ */ /* * The following parts are Copyright of the individual authors. * www - http://www.harbour-project.org * * Copyright 1999 Jose Lalin * DESCEND() documentation * * Copyright 2000 Luiz Rafael Culik * 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 * * 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() --> lAlpha * $ARGUMENTS$ * Any character string * $RETURNS$ * lAlpha Logical true (.T.) or false (.F.). * $DESCRIPTION$ * This function return a logical true (.T.) if the first character * in 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' ) ) * $TESTS$ * $STATUS$ * R * $COMPLIANCE$ * This function is CA-Clipper compliant * $PLATFORMS$ * $FILES$ * $SEEALSO$ * ISDIGIT(),ISLOWER(),ISUPPER(),LOWER(),UPPER() * $END$ */ /* $DOC$ * $FUNCNAME$ * ISDIGIT() * $CATEGORY$ * Strings * $ONELINER$ * Checks if leftmost character is a digit character * $SYNTAX$ * ISDIGIT() --> lDigit * $ARGUMENTS$ * Any character string * $RETURNS$ * lDigit Logical true (.T.) or false (.F.). * $DESCRIPTION$ * This function takes the caracter string 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' ) ) * $TESTS$ * $STATUS$ * R * $COMPLIANCE$ * This function is CA-Clipper compliant * $PLATFORMS$ * $FILES$ * $SEEALSO$ * ISALPHA(),ISLOWER(),ISUPPER(),LOWER(),UPPER() * $END$ */ /* $DOC$ * $FUNCNAME$ * ISUPPER() * $CATEGORY$ * Strings * $ONELINER$ * Checks if leftmost character is an uppercased letter. * $SYNTAX$ * ISUPPER() --> lUpper * $ARGUMENTS$ * Any character string * $RETURNS$ * lUpper Logical true (.T.) or false (.F.). * $DESCRIPTION$ * This function takes the caracter string 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' ) ) * $TESTS$ * $STATUS$ * R * $COMPLIANCE$ * This function is CA-Clipper compliant * $PLATFORMS$ * $FILES$ * $SEEALSO$ * ISALPHA(),ISLOWER(),ISDIGIT(),LOWER(),UPPER() * $END$ */ /* $DOC$ * $FUNCNAME$ * ISLOWER() * $CATEGORY$ * Strings * $ONELINER$ * Checks if leftmost character is an lowercased letter. * $SYNTAX$ * ISLOWER() --> lLower * $ARGUMENTS$ * Any character string * $RETURNS$ * lLower Logical true (.T.) or false (.F.). * $DESCRIPTION$ * This function takes the caracter string 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' ) ) * $TESTS$ * $STATUS$ * R * $COMPLIANCE$ * This function is CA-Clipper compliant * $PLATFORMS$ * $FILES$ * $SEEALSO$ * ISALPHA(),ISDIGIT(),ISUPPER(),LOWER(),UPPER() * $END$ */ /* $DOC$ * $FUNCNAME$ * LTRIM() * $CATEGORY$ * Strings * $ONELINER$ * Removes leading spaces from a string * $SYNTAX$ * LTRIM() --> * $ARGUMENTS$ * Character expression with leading spaces * $RETURNS$ * The same character expression with leading spaces removed * $DESCRIPTION$ * This function trims the leading space blanl * $EXAMPLES$ * ? QOUT( LTRIM("HELLO ")) * $TESTS$ * * $STATUS$ * R * $COMPLIANCE$ * This functions is CA-CLIPPER compatible * $PLATFORMS$ * * $FILES$ * * $SEEALSO$ * TRIM(),RTRIM(),ALLTRIM() * $END$ */ /* $DOC$ * $FUNCNAME$ * AT() * $CATEGORY$ * Strings * $ONELINER$ * Locates the position of a substring in a main string. * $SYNTAX$ * AT(,) --> nPos * $ARGUMENTS$ * Substring to search for * 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 for the characters in * the first string . If the substring is not contained within * the second expression,the function will return 0. * $EXAMPLES$ * QOUT( "at( 'cde', 'abcdefgfedcba' ) = '" +; * at( 'cde', 'abcsefgfedcba' ) + "'" ) * $TESTS$ * $STATUS$ * R * $COMPLIANCE$ * This function is CA-Clipper compatible. * $PLATFORMS$ * $FILES$ * $SEEALSO$ * RAT() * $END$ */ /* $DOC$ * $FUNCNAME$ * RAT() * $CATEGORY$ * Strings * $ONELINER$ * Searches for a substring from the right side of a string. * $SYNTAX$ * RAT(,) --> nPos * $ARGUMENTS$ * Substring to search for * Main string * $RETURNS$ * RAT() return the location of beginnig position. * $DESCRIPTION$ * This function searches througt for the first existence * of .The search operation is performed from the right side * of to the left. If the function is unable to find any * occurence of in ,the value of the function will be 0. * $EXAMPLES$ * QOUT( "rat( 'cde', 'abcdefgfedcba' ) = '" +; * rat( 'cde', 'abcsefgfedcba' ) + "'" ) * $TESTS$ * * $STATUS$ * R * $COMPLIANCE$ * Will not work with a search string > 64 KB on some platforms * $PLATFORMS$ * $FILES$ * $SEEALSO$ * AT(),SUBSTR(),RIGHT() * $END$ */ /* $DOC$ * $FUNCNAME$ * LEFT() * $CATEGORY$ * Strings * $ONELINER$ * Extract the leftmost substring of a character expression * $SYNTAX$ * LEFT(,) --> * $ARGUMENTS$ * Main character to be parsed * Number of bytes to return beggining at the leftmost position * $RETURNS$ * Substring of evaluation * $DESCRIPTION$ * This functions returns the leftmost characters of . * It is equivalent to the following programing expression: * SUBSTR(,1, * $EXAMPLES$ * ? QOUT(LEFT('HELLO HARBOUR',5)) * $TESTS$ * * $STATUS$ * R * $COMPLIANCE$ * This functions is CA CLIPPER compatible * $PLATFORMS$ * * $FILES$ * * $SEEALSO$ * SUBSTR(),RIGHT(),AT(),RAT() * $END$ */ /* $DOC$ * $FUNCNAME$ * RIGHT() * $CATEGORY$ * Strings * $ONELINER$ * Extract the rightmost substring of a character expression * $SYNTAX$ * SUBSTR(,) --> * $ARGUMENTS$ * Character expression to be parsed * Number of bytes to return beggining at the rightmost position * $RETURNS$ * Substring of evaluation * $DESCRIPTION$ * This functions returns the rightmost characters of . * * $EXAMPLES$ * ? QOUT(RIGHT('HELLO HARBOUR',5)) * $TESTS$ * * $STATUS$ * R * $COMPLIANCE$ * This functions is CA CLIPPER compatible * $PLATFORMS$ * * $FILES$ * * $SEEALSO$ * SUBSTR(),LEFT(),AT(),RAT() * $END$ */ /* $DOC$ * $FUNCNAME$ * SUBSTR() * $CATEGORY$ * Strings * $ONELINER$ * Returns a substring from a main string * $SYNTAX$ * SUBSTR(,[,)] --> * $ARGUMENTS$ * Character expression to be parsed * Start position * Number of characters to return * $RETURNS$ * Substring of evaluation * $DESCRIPTION$ * This functions returns a character string formed from , * starting at the position of and continuing on for a * lenght of characters. If is not specified, the value * will be all remaining characters from the position of . * The value of 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 . * $EXAMPLES$ * FUNCTION MAIN() * LOCAL X:=REPLICATE('ABCD',70000) * * ? QOUT(SUBSTR(X,65519,200) * * RETURN NIL * $TESTS$ * ? QOUT(SUBSTR('HELLO HARBOUR',5) * $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$ * * $FILES$ * * $SEEALSO$ * LEFT(),AT(),RIGHT() * $END$ */ /* $DOC$ * $FUNCNAME$ * STR() * $CATEGORY$ * Run-time Library, Strings * $ONELINER$ * Convert a numeric expression to a character string. * $SYNTAX$ * STR(, [], []) --> cNumber * $ARGUMENTS$ * is the numeric expression to be converted to a character * string. * is the length of the character string to return, including * decimal digits, decimal point, and sign. * is the number of decimal places to return. * $RETURNS$ * STR() returns 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 * --------------------------------------------------------------- * 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 * --------------------------------------------------------------- * $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 is less than the number of whole number digits in * , STR() returns asterisks instead of the number. * * * If 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 is specified but 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$ * CA-Clipper compatible. * $SEEALSO$ * STRZERO(),VAL() * $END$ */ /* $DOC$ * $FUNCNAME$ * STRZERO() * $CATEGORY$ * Run-time Library, Strings * $ONELINER$ * Convert a numeric expression to a character string, zero padded. * $SYNTAX$ * STRZERO(, [], []) --> cNumber * $ARGUMENTS$ * is the numeric expression to be converted to a character * string. * is the length of the character string to return, including * decimal digits, decimal point, and sign. * is the number of decimal places to return. * $RETURNS$ * STRZERO() returns 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 * --------------------------------------------------------------- * 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 * --------------------------------------------------------------- * $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 is less than the number of whole number digits in * , STR() returns asterisks instead of the number. * * * If 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 is specified but 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" * $TESTS$ * see the regression test suit for comprehensive tests. * $STATUS$ * R * $COMPLIANCE$ * CA-Clipper compatible (it was not mentioned in the docs though). * $SEEALSO$ * STR(),VAL() * $END$ */ /* $DOC$ * $FUNCNAME$ * HB_VALTOSTR() * $CATEGORY$ * Strings * $ONELINER$ * Converts any scalar type to a string. * $SYNTAX$ * HB_VALTOSTR( ) * $ARGUMENTS$ * is any scalar argument. * $RETURNS$ * A string representation of 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$ * HB_VALTOSTR() is a Harbour enhancement. * $SEEALSO$ * STR(),VAL() * $END$ */ /* $DOC$ * $FUNCNAME$ * LEN() * $CATEGORY$ * Strings * $ONELINER$ * Returns size of a string or size of an array. * $SYNTAX$ * LEN( | ) --> * $ARGUMENTS$ * 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 * $TESTS$ * function Test() * LOCAL cName := "" * ACCEPT "Enter your name: " TO cName * ? Len( cName ) * return nil * $STATUS$ * R * $COMPLIANCE$ * LEN() is fully CA-Clipper compliant. * $SEEALSO$ * EMPTY(),RTRIM(),LTRIM(),AADD(),ASIZE() * $END$ */ /* $DOC$ * $FUNCNAME$ * EMPTY() * $CATEGORY$ * Conversion * $ONELINER$ * Checks if the passed argument is empty. * $SYNTAX$ * EMPTY( ) --> * $ARGUMENTS$ * 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" ) * $TESTS$ * function Test() * ? Empty( 1 ) --> .f. * ? Empty( Date() ) --> .f. * ? Empty( .f. ) --> .t. * return nil * $STATUS$ * R * $COMPLIANCE$ * EMPTY() is fully CA-Clipper compliant. * $SEEALSO$ * LEN() * $END$ */ /* $DOC$ * $FUNCNAME$ * DESCEND() * $CATEGORY$ * Conversion * $ONELINER$ * Inverts an expression of string, logical, date or numeric type. * $SYNTAX$ * DESCEND( ) --> * $ARGUMENTS$ * 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$ * DESCEND() is fully CA-Clipper compliant. * $SEEALSO$ * INDEX,SEEK * $END$ */ /* $DOC$ * $FUNCNAME$ * HB_ANSITOOEM() * $CATEGORY$ * Strings * $ONELINER$ * Convert a windows Character to a Dos based character * $SYNTAX$ * HB_ANSITOOEM() -> cDosString * $ARGUMENTS$ * Windows ansi string to convert to DOS oem String * $RETURNS$ * cDosString Dos based string * $DESCRIPTION$ * This function converts each character in to the corresponding * character in the MS-DOS (OEM) character set.The character expression * should contain characters from the ANSI character set. * If a character in doesn't have a MS-DOS equivalent, the * character is converted to a similar MS-DOS character. * $EXAMPLES$ * ? HB_OEMTOANSI("Harbour") * $TESTS$ * * $STATUS$ * R * $COMPLIANCE$ * This function is a Harbour extension * $PLATFORMS$ * This functions work only on Windows Plataform * $FILES$ * * $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() -> cDosString * $ARGUMENTS$ * DOS (OEM) string to convert to WINDOWS (ANSI) String * $RETURNS$ * cDosString WINDOWS based string * $DESCRIPTION$ * This function converts each character in to the corresponding * character in the Windows (ANSI) character set.The character expression * should contain characters from the OEM character set. * If a character in doesn't have a ANSI equivalent, the * character is remais the same. * $EXAMPLES$ * ? HB_OEMTOANSI("Harbour") * $TESTS$ * $STATUS$ * R * $COMPLIANCE$ * This function is a Harbour extension * $PLATFORMS$ * This functions work only on Windows Plataform * $FILES$ * * $SEEALSO$ * HB_ANSITOOEM() * $END$ */ /* $DOC$ * $FUNCNAME$ * LOWER() * $CATEGORY$ * Strings() * $ONELINER$ * Universally lowercases a character string expression. * $SYNTAX$ * LOWER( ) --> cLowerString * $ARGUMENTS$ * Any character expression. * $RETURNS$ * Lowercased value of * $DESCRIPTION$ * This function converts any character expression passes as * to its lowercased representation.Any nonalphabetic character withing * will remain unchanged. * $EXAMPLES$ * ? Lower("HARBOUR") * ? Lower("Hello All") * $STATUS$ * R * $COMPLIANCE$ * This function is CA-Clipper compatible * $PLATFORMS$ * ALL * $SEEALSO$ * UPPER(),ISLOWER(),ISUPPER() * $END$ */ /* $DOC$ * $FUNCNAME$ * UPPER() * $CATEGORY$ * Strings * $ONELINER$ * Converts a character expression to uppercase format * $SYNTAX$ * UPPER( ) --> cUpperString * $ARGUMENTS$ * Any character expression. * $RETURNS$ * Uppercased value of * $DESCRIPTION$ * This function converts all alpha characters in to upper * case values and returns that formatted character expression. * $EXAMPLES$ * ? UPPER("harbour") * ? UPPER("Harbour") * $STATUS$ * R * $COMPLIANCE$ * This function is CA-Clipper compatible * $PLATFORMS$ * All * $SEEALSO$ * LOWER(),ISUPPER(),ISLOWER() * $END$ */