fivedev/harbour-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9e1b00d011c7e598c1166af8da170231749bbb38
harbour-core/harbour/doc/en/string.txt
Viktor Szakats d467c175a1 2012-07-05 12:47 UTC+0200 Viktor Szakats (harbour syenar.net) 
* doc/en/sayget.txt
  * doc/en/set.txt
  * doc/en/setmode.txt
  * doc/en/string.txt
  * doc/en/subcodes.txt
    ! More spelling.
      by Alexey Myronenko
2012-07-05 10:48:28 +00:00

1565 lines
42 KiB
Plaintext
Raw Blame History

/*
* $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 character 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 character 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 position 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 beginning position.
* $DESCRIPTION$
* This function searches through <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
* occurrence 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 beginning 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 beginning 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( STOD( "20010101" ) ) == "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$
* PROCEDURE Test()
* LOCAL cName := ""
* ACCEPT "Enter your name: " TO cName
* ? LEN( cName )
* RETURN
* $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$
* PROCEDURE 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
* $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 remains 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 non alphabetic 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 integer 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( "¹" )
* $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 formatted string with out any blank spaced.
* $DESCRIPTION$
* This function returns the value of <cString> with any trailing blank
* removed.
*
* This function is identical 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 formatted string with out any blank spaced.
* $DESCRIPTION$
* This function returns the value of <cString> with any trailing blank
* removed.
*
* This function is identical 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 contain 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 available.
*
* 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$
* PROCEDURE 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
*
* 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 previously 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>],
* [<nOccurrences>] ) --> 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 occurrence to be replaced
*
* <nOccurrences> Number of occurrence to replace
* $RETURNS$
* <cReturn> Formated string
* $DESCRIPTION$
* This function searches for any occurrence of <cLocString> in <cString>
* and replaces it with <cRepString>. If <cRepString> is not specified, a
* NULL byte will replace <cLocString>.
*
* If <nPos> is used, its value defines the first occurrence to be
* replaced. The default value is 1. Additionally, if used, the value of
* <nOccurrences> tell the function how many occurrences of <cLocString>
* in <cString> are to the replaced. The default of <nOccurrences> 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> ) --> cFormatted
* $ARGUMENTS$
* <xExpression> Any expression to be formated.
*
* <cTemplate> Character string with picture template
* $RETURNS$
* <cFormatted> 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 available 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 non template 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 formatted 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
* $ Dollar 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$
*/
Reference in New Issue View Git Blame Copy Permalink