53 String Functions - Deutschsprachige FoxPro User...

String Functions

String Functions

String Functions

STR_addcod() : Adds an ASCII code to each character of a string.

SyntaxSTR_addcod( szString,nCode ) szResult

ParametersszString string to process.nCode ASCII code to add to each character.

ReturnsszResult resulting string.

Example? STR_addcod( "12345678",1 ) && "23456789"

STR_AllChars() : Returns all the characters found in a string in a sorted manner.

RemarkThis algorithm is used in SCRABBLE for example … to locate ANY word that contains all letters, or 7 letters, or 6 letters, etc.. Very efficient.

SyntaxSTR_AllChars( szString[,nType] ) szResult

ParametersszString string to process.nType Type of treatment: 0 … case-sensitive; 1 … uses uppercase algorithm; 2 … uses lowercase

algorithm. This parameter is optional. By default, 0 is used.


ExampleLOCAL szString

m.szString = "Hello World"

? STR_AllChars( m.szString ) && "HWdelor"? STR_AllChars ( m.szString,0 ) && "HWdelor"? STR_AllChars ( m.szString,1 ) && "DEHLORW"? STR_AllChars ( m.szString,2 ) && "dehlorw"

STR_ascii() : Forms a number based on each character value.

SyntaxSTR_ascii( szString ) nResult

ParametersszString string to process.

String FunctionsReturnsnResult resulting number.

Example? STR_ascii ( "AA" ) && 130? STR_ascii2( "AA" ) && 195? STR_ascii ( "AB" ) && 131? STR_ascii2( "AB" ) && 197

STR_ascii2() : Forms a number based on each character value multiplied by its position.

SyntaxSTR_ascii2( szString ) nResult


ReturnsnResult resulting number.

Example? STR_ascii ( "AA" ) && 130? STR_ascii2( "AA" ) && 195? STR_ascii ( "AB" ) && 131? STR_ascii2( "AB" ) && 197

STR_Ascii2Ebcdic() : Converts a string to its EBCDIC equivalent.

SyntaxSTR_Ascii2Ebcdic( szAscii ) szEbcdic

ParametersszAscii string to process.

ReturnsszEbcdic resulting number.


m.szString = STR_Ascii2Ebcdic( "Hello World" )? m.szString && "È…““–@æ–™“„"? STR_ Ebcdic2Ascii( m.szString ) && "Hello World"

STR_AtLine() : Determines the number of the line a given position belongs to.

SyntaxSTR_AtLine( n,szString ) nLine

String FunctionsParametersn the position.szString string to process.

ReturnsnLine line number. Please note that unlike VFP native ATLINE() function, the STR_AtLine() function

does not rely on SET MEMOWIDTH to calculate the line number: only the sequence CR + LF ( CHR(13) + CHR(10) ) controls the line jump.

Example&& This example searches an entire source code (.PRG) and locates&& Change Control Tags so that they can be documented automatically&& A Change Control tag has the following form:&&&& <cc date="20010520120000" auth="Anurak">&& ... the code that is enclosed within the tags&& </cc date="20010520120000">

&& As you can see there is an opening tag, and a closing tag&&LOCAL szCodeLOCAL nStartLOCAL nEndLOCAL nEnd2LOCAL nMatchLOCAL szTokenLOCAL iLOCAL szDateTimeLOCAL szAuthorLOCAL szRefLOCAL szCommentLOCAL nAtLine && Starting lineLOCAL nAtLine2 && Ending line

&& m.szFile is the .PRG file to readm.szCode = FILETOSTR( m.szFile )

&& We won't use this variable but we need it for STR_like()m.nMatch = 0&& Staring position to start searching (STR_like())m.nStart = 1&& Without regard to caseSTR_LikeCase( .F. )

WAIT WINDOW "Parsing the code. Please wait..." NOWAIT

IF ( ! EMPTY( m.szCode ) )

m.n && Process the entire string DO WHILE ( .T. )

&& If we can find the opening tag … where does it end? m.nEnd = STR_Like( [*<cc*date="*"*auth="*"*>*],m.szCode,3,@nMatch,m.nStart )

&& Did we find the opening tag? IF ( m.nEnd != 0 ) && We found it … and because we asked FOCUS to store the 3rd placeholder && we now can simply extract the Date/Time value m.szDateTime = STR_LikeGetToken()

&& That's the line number where we found the opening tag m.nAtLine = STR_AtLine( m.nEnd,m.szCode )

&& Let's get the author name now IF ( STR_Like( [*<cc*date="*"*auth="*"*>*],m.szCode,5,@nMatch,m.nStart ) != 0 ) m.szAuthor = STR_LikeGetToken()

String Functions ELSE m.szAuthor = "" ENDIF

&& Let's get an optional reference number (in case the Change Control && has been assigned such a number) IF ( STR_Like( [*<cc*date="*"*ref="*"*>*],m.szCode,5,@nMatch,m.nStart ) != 0 ) m.szRef = STR_LikeGetToken() ELSE m.szRef = "" ENDIF

&& If we want to be exhaustive, we might as well && extract an optional comment (sounds a good idea) IF ( STR_Like([*<cc*date="*"*comment="*"*>*],m.szCode,5,@nMatch,m.nStart) != 0 ) m.szComment = STR_LikeGetToken() ELSE m.szComment = "" ENDIF

&& Let's remember where the oepning tag was ending … because, && this will be used to continue the scanning of the source code m.nStart = m.nEnd

&& Searching for the closing tag now m.nEnd2 = STR_Like( [*</cc*date="] + m.szDateTime + ; [*>*],m.szCode,3,@nMatch,m.nEnd )

&& If we found it IF ( m.nEnd2 != 0 ) && To which line of the source code this tag belongs to? m.nAtLine2 = STR_AtLine( m.nEnd2,m.szCode ) ELSE m.nAtLine2 = -1 ENDIF

&& Imagine we put what we found in a list control && OK, ok … we don't use the reference number nor do && we use the comment! But this is merely an example, right? .lstCCtrl.AddItem( "CC Author: " + m.szAuthor + " -- " + ; "Date : " + m.szDateTime + " -- " + ; "Start:" + ALLTRIM( STR( m.nAtLine ) ) + " ... " + ; "End:" + ALLTRIM( STR( m.nAtLine2 ) ) ; ) ELSE && No opening tag found => we can exit the routine EXIT ENDIF

ENDDO

ENDIF

WAIT WINDOW "Done!" NOWAIT

STR_balanc() : Finds position where a given character is balanced with another.

SyntaxSTR_balanc( szString,szDelimiters,nOccurrence ) nPosition

ParametersszString string to process.szDelimiters two characters string.nOccurrence occurrence to check for.

String FunctionsReturnsnPosition position where character is balanced. szString starts at 1. If not found, 0.

ExampleLOCAL szVar

szVar = "MyFunc( People( 1,23,78 ))"? STR_balanc( szVar,"()",2 ) && 26 = position where closing && parenthesis is found

STR_char() : Extracts the rest of a string.

AliasSTR_rest().

CautionNo test is made on the parameters. Passing wrong parameters can produce unexpected results.

SyntaxSTR_char( szString,nPosition ) szResult

ParametersszString string to process.nPosition position at which extraction starts.


Example? STR_char( "Hello World",3 ) && "llo World"

STR_chrcnt() : Counts occurrences of a character in a string.

SyntaxSTR_chrcnt( szString,cChar ) nOccurrences

ParametersszString string to process.cChar character to search for.

ReturnsnOccurrences number of occurrences of cChar in szString.

Example? STR_chrcnt( "Hello World","l" ) // 3

STR_chrswa() : Swaps one character with another within a string.

SyntaxSTR_chrswa( szString,cToBeReplaced,cReplacement ) szNewString

String FunctionsParametersszString string to be processed.cToBeReplaced character that should be replaced with cReplacement.cReplacement character to substitute to cToBeReplaced.

ReturnsszNewString resulting string.

Example? STR_chrswa( "Hello World","l","A" ) && "HeAAo WorAd"

STR_comma() : Formats a string that only contains digits.

SyntaxSTR_comma( szString,cComma ) szNumber

ParametersszString string to be processed.cComma character that represents a comma.

ReturnsszNumber resulting string.

Example? STR_comma( "1024.78","," ) && "1.024,78"? STR_comma( "1024.78","." ) && "1,024.78"

STR_CompareStrings() : Compares two character strings, using the current User Locale as the basis for the comparison.

SyntaxSTR_CompareStrings( szString1,szString2,nFlags ) nResult

ParametersszString1 first string to compare.szString2 second string to compare.nFlags comparison flags. These flags indicate how the function compares the two strings. By default,

these flags are not set. This parameter can specify zero to get the default behavior, or it can be any combination of the following values :

Manifest Constant Value MeaningNORM_IGNORECASE 0x00000001 Ignore case.NORM_IGNOREKANATYPE 0x00010000 Do not differentiate between Hiragana and

Katakana characters. Corresponding Hiragana and Katakana characters compare as equal.

NORM_IGNORENONSPACE 0x00000002 Ignore non-spacing characters.NORM_IGNORESYMBOLS 0x00000004 Ignore symbols.NORM_IGNOREWIDTH 0x00020000 Do not differentiate between a single-byte

character and the same character as a double-byte character.

SORT_STRINGSORT 0x00001000 Treat punctuation the same as symbols.

String FunctionsReturnsnResult If the function succeeds, the return value is one of the following values :

Value Meaning1 szString1 parameter is less in lexical value than the string pointed to by the

szString2 parameter.2 szString1 is equal in lexical value to szString2.3 szString1 is greater in lexical value than szString2.

If the function fails, the return value is zero.

STR_Compare() : Compares two character strings, and reports where they differ.

SyntaxSTR_Compare( szString1,szString2[,nFlags] ) nOffset

ParametersszString1 first string to compare.szString2 second string to compare.nFlags comparison flags (optional). When not passed, the two strings are strictly compared. The only

supported flag is:

Manifest Constant Value MeaningNORM_IGNOREWIDTH 0x00020000 Do not differentiate between a single-byte

character and the same character as a double-byte character.

ReturnsnResult 0 indicates that both strings are identical; otherwise, the return value is the offset where the

strings differ.

STR_ConvertA2B() : Converts a character string based on an internal conversion table.

RemarkSTR_SetConvTable()can be used to set the internal conversion table used by the STR_ConvertA2B() and STR_ConvertB2A() functions.All together, these functions permit to convert character strings: a 'A' must be transformed into a 'C', a 'C' into a 'B', a 'B' into a 'A', … It can be used to scramble strings. Likewise, it can be used to issue ASCII to EBCDIC transformations.

SyntaxSTR_ConvertA2B( szStr ) szResult

ParametersszStr the string to treat.

ReturnsszResult szStr transformed thanks to the internal conversion table. The internal conversion table can be

altered thanks to STR_SetConvTable() and STR_SetCharConversion().

ExampleLOCAL iCharH,iCharWLOCAL szString

m.iCharH = ASC( 'H' )m.iCharW = ASC( 'W' )m.szString = "Hello World"

String Functions&& Every 'H' should be turned into a 'W'STR_SetCharConversion( m.iCharH,m.iCharW )

&& Every 'W' should be turned into a 'H'STR_SetCharConversion( m.iCharW,m.iCharH )

m.szTransformed = STR_ConvertA2B( m.szString ) && "Wello Horld"? STR_ConvertB2A( szTransformed ) && "Hello World"

See alsoSTR_ConvertB2A(), STR_SetCharConversion(), STR_SetConvTable().

STR_ConvertB2A() : Reverses the conversion set by the STR_ConvertA2B() function.

RemarkSTR_SetConvTable()can be used to set the internal conversion table used by the STR_ConvertA2B() and STR_ConvertB2A() functions.All together, these functions permit to convert character strings: a 'A' must be transformed into a 'C', a 'C' into a 'B', a 'B' into a 'A', … It can be used to scramble strings. Likewise, it can be used to issue ASCII to EBCDIC transformations.

SyntaxSTR_ConvertB2A( szStr ) szResult

ParametersszStr the string to treat.

ReturnsszResult szStr transformed thanks to the internal conversion table. The internal conversion table can be

altered thanks to STR_SetConvTable() and STR_SetCharConversion().



&& Every 'H' should be turned into a 'W'STR_SetCharConversion( m.iCharH,m.iCharW )



See alsoSTR_ConvertA2B(), STR_SetCharConversion(), STR_SetConvTable().

STR_cpbrk() : Finds the 1st occurrence in a string of any character from another string. String result.

SyntaxSTR_cpbrk( szString1,szString2 ) szString

String FunctionsParametersszString1 string to be search for.szString2 string to look for characters.

ReturnsszString resulting character string.

Example? STR_cpbrk( "The 3 men and 2 dogs ate 5 pigs","0123456789" )&& "3 men and 2 dogs ate 5 pigs"

STR_Decode64() : Decodes a base 64 encoded string.

SyntaxSTR_Decode64( szBase64 ) szString

ParametersszBase64 the character string that is base 64 encoded.

ReturnsszString original string.

ExampleLOCAL szStringLOCAL szEncryptedLOCAL szDecrypted


m.szEncrypted = STR_Encode64( m.szString ) && "SGVsbG8gV29ybGQ="m.szDecrypted = STR_Decode64( m.szEncrypted ) && "Hello World"

IF ( m.szDecrypted == m.szString ) ? "It worked"ELSE ? "It didn't worked"ENDIF

STR_dionly() : Keeps digits only.

SyntaxSTR_dionly( szString ) szResult

ParametersszString string to be processed.

ReturnsszResult resulting string. Only digits and decimal separator are kept (".").

Example? STR_dionly( "Hello the 101 dogs" ) && "101"

STR_Ebcdic2Ascii() : Converts a string to its ASCII equivalent.

SyntaxSTR_Ebcdic2 Ascii(szEbcdic ) szAscii

String FunctionsParametersszEbcdic string to process.

ReturnsszAscii resulting number.


m.szString = STR_Ascii2Ebcdic( "Hello World" )? m.szString && "È…““–@æ–™“„"? STR_ Ebcdic2Ascii( m.szString ) && "Hello World"

STR_Encode64() : Encodes a string in base 64.

SyntaxSTR_Encode64( szString ) szBase64


ReturnsszBase64 the character string base 64 encoded.

ExampleLOCAL szStringLOCAL szEncryptedLOCAL szDecrypted


m.szEncrypted = STR_Encode64( m.szString ) && "SGVsbG8gV29ybGQ="m.szDecrypted = STR_Decode64( m.szEncrypted ) && "Hello World"

IF ( m.szDecrypted == m.szString ) ? "It worked"ELSE ? "It didn't worked"ENDIF

STR_encrypt() : Encrypts a string.

RemarkThe function can be applied on its own return to retrieve the original string.

SyntaxSTR_encrypt( szString,szCode ) szResult

ParametersszString string to process.szCode code for encryption.

ReturnsszResult the encrypted string.

String FunctionsExampleLOCAL szEncryptedLOCAL szCode

szCode = "This is a regular string"szEncrypted = STR_encrypt( "Hello World",szCode )

IF ( STR_encrypt( szEncrypted,szCode ) != "Hello World" ) ? "The string cannot be decrypted! Strange!"ENDIF

STR_end() : Does a string end with a given value?

SyntaxSTR_end( szString1,szString2 ) lResult

ParametersszString1 string to process.szString2 string to look for.

ReturnslResult .T. if szString1 ends with szString2.

Example? STR_end( "Hello World","rld" ) && .T.

See alsoSTR_start()

STR_exclude() : Excludes characters that are in a string.

AliasExclude(), STR_exclud(), ExcludeChars(), ExcludeChar(), STR_Discard(), STR_eliminate().

SyntaxSTR_exclude( szString,szToExclude ) szResult

ParametersszString string to process.szToExclude string from which each character should be excluded from szString.


Example? STR_exclude( "Hello World","Hlo") && "e Wrd"

STR_first() : Finds the first character that is not a space.

SyntaxSTR_first( szString ) cChar

ParametersszString string to find the first character from.

String FunctionsReturnscChar first character that is not a space in szString. The string is processed from right to left.

Example? STR_first( "Hello World" ) && "H"? STR_first( " Hello" ) && "H"

See alsoSTR_last()

STR_FormatByteSize() : Converts a numeric value into a string that represents the number expressed as a size value in bytes, kilobytes, megabytes, or gigabytes, depending on the size.

SyntaxSTR_FormatByteSize( n ) szSize

Parametersn integer to treat as a size in bytes.

ReturnsszSize resulting number.

Example? STR_FormatByteSize(100) && "100 bytes"? STR_FormatByteSize(1000) && "1000 bytes"? STR_FormatByteSize(2000) && "1,95 KB"? STR_FormatByteSize(1024*1024*1024) && "1,00 GB"

STR_getoff() : Gets the internal offset position.

CommentSTR_getoff() is one of the token functions. This function is intended to be used when accessing one token after another. In this sense, tokens are not reached at random. STR_getoff() interrogates the internal counter Offset.

SyntaxSTR_getoff() nOffset

ParametersNone.

ReturnsnOffset value returned by this function indicates the offset position prior STR_toknex() did reach when

retrieving tokens from a string.

See AlsoSTR_tokini(), STR_toknex(), STR_tokfin().

STR_GeneratePassword() : Generates a random password.

SyntaxSTR_GeneratePassword( [nLength[,nStrategy]] ) szPwd

String FunctionsParametersnLength optional length of the generated password. By default szPwd is 8 characters long.nStrategy optional strategy when generating the password. By default, each character of szPwd is

generated using a random strategy.

Strategy Description0 szPwd will contain digits only.1 szPwd will contain uppercase letters only.2 szPwd will contain lowercase letters only.

ReturnsszPwd the generated password.

Example? STR_GeneratePassword() && "M5RPY453"? STR_GeneratePassword( 10 ) && "31B12cT9LE"? STR_GeneratePassword( 10,0 ) && "5709359440"? STR_GeneratePassword( 10,1 ) && "QVAADIVKFL"? STR_GeneratePassword( 10,2 ) && "gpjjpfdojr"

STR_hexa() : Hexadecimal equivalent of a string.

CautionThe STR_hexa() function does not evaluate correctly when accented characters must be converted.

Aliasstoh()

SyntaxSTR_hexa( szString ) szHex


ReturnsszHex hexadecimal equivalent of szString.

Example? STR_hexa( "DVL Group" ) && "44564C2047726F7570"? STR_htos("44564C2047726F7570" ) && "DVL Group"

See alsoNUM_hexa(), STR_htos(), NUM_htoi()

STR_htos() : Original string corresponding to an hexadecimal string.

CautionThe STR_htos() function does not evaluate correctly when it must restore accented characters must be converted.

Aliashtos()

SyntaxSTR_htos( cHexaString ) szString

String FunctionsParameterscHexaString string to process.

ReturnsszString original string.

Example? STR_hexa( "DVL Group" ) && "44564C2047726F7570"? STR_htos("44564C2047726F7570" ) && "DVL Group"

See alsoSTR_hexa()

STR_IsAlpha() : Determines if a given string contains only alpha characters.

Remark

Unlike the ISALPHA() function of Visual FoxPro which only considers the first character, this makes it possible to examine the entire string, or only a portion of it.

SyntaxSTR_IsAlpha( szString[,nStart[,nCount]] ) lResult

ParametersszString string to process.nStart specifies the position in the character string to examine. This parameter is optional. Default is 0.nCount specifies the number of characters to test. This parameter is optional. Default is equal to the

length of the string from the nStart position.

ReturnslResult .T. if the string is only made of alpha characters. .F. otherwise.

Example? STR_IsAlpha( "Hello All Of You" ) && .F.? STR_IsAlpha( "Hello All Of You",1,5 ) && .T.? STR_IsAlpha( "Hello All Of You",1,6 ) && .F.

See alsoSTR_IsUpper(), STR_IsLower(), STR_IsAlphaNumeric(), STR_IsPunct(), STR_IsSpace(), STR_IsPrint(), STR_IsGraph(), STR_IsVowel(), STR_IsConsonant()

STR_IsAlphaNumeric() : Determines if a given string contains only alphanumeric characters.

SyntaxSTR_IsAlphaNumeric( szString[,nStart[,nCount]] ) lResult



String FunctionsReturnslResult .T. if the string is only made of alphanumeric characters. .F. otherwise.

Example? STR_IsAlphaNumeric( "MYFILE105.EXT" ) && .F.? STR_IsAlphaNumeric( "MYFILE105.EXT",1,9 ) && .T.? STR_IsAlphaNumeric( "MYFILE105.EXT",1,10 ) && .F.

See alsoSTR_IsUpper(), STR_IsLower(), STR_IsAlpha(), STR_IsPunct(), STR_IsSpace(), STR_IsPrint(), STR_IsGraph(), STR_IsVowel(), STR_IsConsonant()

STR_IsPunct() : Determines if a given string contains only punctuation marks.

SyntaxSTR_IsPunct( szString[,nStart[,nCount]] ) lResult



ReturnslResult .T. if the string is only made of punctuation marks. .F. otherwise.

Example? STR_IsPunct( "MYFILE105.EXT" ) && .F.? STR_IsPunct( "MYFILE105.EXT",10 ) && .F.? STR_IsPunct( "MYFILE105.EXT",10,1 ) && .T.

See alsoSTR_IsUpper(), STR_IsLower(), STR_IsAlpha(), STR_IsAlphaNumeric(), STR_IsSpace(), STR_IsPrint(), STR_IsGraph(), STR_IsVowel(), STR_IsConsonant()

STR_IsSpace() : Determines if a given string contains only spaces.

SyntaxSTR_IsSpace( szString[,nStart[,nCount]] ) lResult



ReturnslResult .T. if the string is only made of spaces. .F. otherwise. The following characters are considered

to be spaces : CHR(9), CHR(10), CHR(11), CHR(12), CHR(13), CHR(32).

See alsoSTR_IsUpper(), STR_IsLower(), STR_IsAlpha(), STR_IsAlphaNumeric(), STR_IsPunct(), STR_IsPrint(), STR_IsGraph(), STR_IsVowel(), STR_IsConsonant()

String FunctionsSTR_IsGraph() : Determines if a given string contains only graph characters.

SyntaxSTR_IsGraph( szString[,nStart[,nCount]] ) lResult



ReturnslResult .T. if the string is only made of spaces. .F. otherwise. Only the representation of any ASCII or

Katakana printable character except a white space are considered to be graph characters : !, ", #, $, %, &, ', (, ), *, +, ,, -, ., /, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, :, ;, <, =, >,?, @, A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z, [, \, ], ^, _, `, a, b, c, d, e, f, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z, {, |, }, ~.

See alsoSTR_IsUpper(), STR_IsLower(), STR_IsAlpha(), STR_IsAlphaNumeric(), STR_IsPunct(), STR_IsPrint(), STR_IsSpace(), STR_IsVowel(), STR_IsConsonant()

STR_IsPrint() : Determines if a given string contains only graph characters.

SyntaxSTR_IsPrint( szString[,nStart[,nCount]] ) lResult



ReturnslResult .T. if and only if the string is only made of single-byte representations of any ASCII or Katakana

printable character including a white space.

See alsoSTR_IsUpper(), STR_IsLower(), STR_IsAlpha(), STR_IsAlphaNumeric(), STR_IsPunct(), STR_IsGraph(), STR_IsSpace(), STR_IsVowel(), STR_IsConsonant()

STR_IsCharAlpha() : Determines if a given character is an alpha character.

Remark

Unlike the ISALPHA() function of Visual FoxPro which only considers the first character, this makes it possible to examine a particular character of the string.

SyntaxSTR_IsCharAlpha( szString[,nPosition] ) lResult

String FunctionsParametersszString string to process.nPosition specifies the position in the character string to examine. Optional parameter.

ReturnslResult .T. if the character is an alpha character. .F. otherwise.

Example? STR_IsCharAlpha( "Hello",1 ) && .T.

See alsoSTR_IsUpper(), STR_IsLower(), STR_IsCharLower(), STR_IsCharUpper(), STR_IsCharAlphaNumeric(), STR_IsCharPunct(), STR_IsCharSpace(), STR_IsCharPrint(), STR_IsCharGraph().

STR_IsCharAlphaNumeric() : Determines if a given character is an alphanumeric character.

Remark

Unlike the ISALPHA() function of Visual FoxPro which only considers the first character and alpha characters, this makes it possible to examine a particular character of the string plus numerics.

SyntaxSTR_IsCharAlphaNumeric( szString[,nPosition] ) lResult

ParametersszString string to process.nPosition specifies the position in the character string to examine. Optional parameter.

ReturnslResult .T. if the character is an alphanumeric character. .F. otherwise.

Example? STR_IsCharAlphaNumeric( "101 dogs",1 ) && .T.

See alsoSTR_IsUpper(), STR_IsLower(), STR_IsCharLower(), STR_IsCharUpper(), STR_IsCharAlpha, STR_IsCharPunct(), STR_IsCharSpace(), STR_IsCharPrint(), STR_IsCharGraph().

STR_IsCharDigit() : Is a given character a digit?

SyntaxSTR_IsCharDigit( szString[,nPosition] ) lResult


ReturnslResult STR_IsCharDigit() returns a .T. value if the character is a digit. Otherwise it returns .F..

See alsoSTR_IsUpper(), STR_IsLower(), STR_IsCharUpper(), STR_IsCharLower(), STR_IsCharAlpha(), STR_IsCharAlphaNumeric(), STR_IsCharPunct(), STR_IsCharPrint(), STR_IsCharSpace().

String FunctionsSTR_IsCharGraph() : Is a given character printable while not being a space?

SyntaxSTR_IsCharGraph( szString[,nPosition] ) lResult


ReturnslResult STR_IsCharGraph() returns a .T. value if the character is a printable character other than a

space. Otherwise it returns .F..

See alsoSTR_IsUpper(), STR_IsLower(), STR_IsCharUpper(), STR_IsCharLower(), STR_IsCharAlpha(), STR_IsCharAlphaNumeric(), STR_IsCharPunct(), STR_IsCharPrint(), STR_IsCharSpace().

STR_IsCharLower() : Determines if a given character of a specified string is a lowercase character.

Remark

Unlike the ISLOWER() function of Visual FoxPro which only considers the first character, this makes it possible to examine a particular character of the string.

SyntaxSTR_IsCharLower( szString[,nPosition] ) lResult


ReturnslResult is the character in a lowercase format? .T. if yes, .F. if not.

Example? STR_IsCharLower( "Hello",1 ) && .F.? STR_IsCharLower( "Hello",2 ) && .T.

See alsoSTR_IsUpper(), STR_IsLower(), STR_IsCharUpper(), STR_IsCharAlpha(), STR_IsCharAlphaNumeric(), STR_IsCharPunct(), STR_IsCharSpace(), STR_IsCharPrint(), STR_IsCharGraph().

STR_IsCharPrint() : Is a given character printable?

SyntaxSTR_IsCharPrint( szString[,nPosition] ) lResult


String FunctionsReturnslResult STR_IsCharPrint() returns a .T. value if the character is a printable character, including the

space character. Otherwise it returns .F..

See alsoSTR_IsUpper(), STR_IsLower(), STR_IsCharUpper(), STR_IsCharLower(), STR_IsCharAlpha(), STR_IsCharAlphaNumeric(), STR_IsCharPunct(), STR_IsCharGraph(), STR_IsCharSpace().

STR_IsCharPunct() : Is a given character a punctuation character?

SyntaxSTR_IsCharPunct( szString[,nPosition] ) lResult


ReturnslResult is the character a punctuation character? STR_IsCharPunct() returns .T. for any printable

character that is not a space character. Otherwise it returns .F..

Example? STR_IsCharPunct( "Hello World.",12 ) && .T.

See alsoSTR_IsUpper(), STR_IsLower(), STR_IsCharUpper(), STR_IsCharLower(), STR_IsCharAlpha(), STR_IsCharAlphaNumeric(), STR_IsCharSpace(), STR_IsCharPrint(), STR_IsCharGraph().

STR_IsCharSpace() : Is a given character a white space character?

SyntaxSTR_IsCharSpace( szString[,nPosition] ) lResult


ReturnslResult is the character a white space character? STR_IsCharSpace() returns a .T. value if the

character is a white-space character (CHR(9), CHR(10), CHR(13), CHR(32)). Otherwise it returns .F..

Example? STR_IsCharSpace( "Hello World",6 ) && .T.

See alsoSTR_IsUpper(), STR_IsLower(), STR_IsCharUpper(), STR_IsCharLower(), STR_IsCharAlpha(), STR_IsCharAlphaNumeric(), STR_IsCharPunct(), STR_IsCharPrint(), STR_IsCharGraph().

String FunctionsSTR_IsCharUpper() : Determines if a given character of a specified string is an uppercase character.

Remark

Unlike the ISUPPER() function of Visual FoxPro which only considers the first character, this makes it possible to examine a particular character of the string.

SyntaxSTR_IsCharUpper( szString[,nPosition] ) lResult


ReturnslResult is the character in an uppercase format? .T. if yes, .F. if not.

Example? STR_IsCharUpper( "Hello",1 ) && .T.? STR_IsCharUpper( "Hello",2 ) && .F.

See alsoSTR_IsUpper(), STR_IsLower(), STR_IsCharLower(), STR_IsCharAlpha(), STR_IsCharAlphaNumeric(), STR_IsCharPunct(), STR_IsCharSpace(), STR_IsCharPrint(), STR_IsCharGraph().

STR_IsCharXDigit() : Determines if a given character of the specified string is a hexadecimal digit.

SyntaxSTR_IsCharXDigit( szString[,nPosition] ) lResult

ParametersszString string to process.nPosition specifies the position in the character string to examine. If not passed, the first character of the

string is examined.

ReturnslResult .T. if the character is a hexadecimal digit; .F. if not.

Example? STR_IsCharXDigit( "0123456789ABCDEF" ) && .T.? STR_IsCharXDigit( "0123456789ABCDEFG",17 ) && .F.

See alsoSTR_IsUpper(), STR_IsCharLower(), STR_IsCharUpper(), STR_IsCharAlpha(), STR_IsCharAlphaNumeric(), STR_IsCharPunct(), STR_IsCharSpace(), STR_IsCharPrint(), STR_IsCharDigit(), STR_IsCharGraph(), STR_IsXDigit().

String FunctionsSTR_IsDigit() : Determines if characters of the specified string are digits.

Remark

Unlike the ISDIGIT() function of Visual FoxPro which only considers the first character, this makes it possible to examine a part of a string or the whole string. The developer can mention a position from where he wants to process the string, and additionally he can mention a number of characters to process.

SyntaxSTR_IsDigit( szString[,nStart[,nLength]] ) lResult

ParametersszString string to process.nStart specifies the position in the character string from where the string is going to be processed.

Optional. When not mentioned, the string is processed from the first position.nLength specifies the number of characters to process. Optional. When not mentioned, the string is

processed from the starting position to the end of the string.

ReturnslResult are all the examined characters digits? .T. if yes, .F. if not.

Example? STR_IsDigit( "Hello101" ) && .F.? STR_IsDigit( "Hello101" ,6 ) && .T.? STR_IsDigit( "Hello101a",6 ) && .F.? STR_IsDigit( "Hello101a",6,3 ) && .T.

See alsoSTR_IsUpper(), STR_IsCharLower(), STR_IsCharUpper(), STR_IsCharAlpha(), STR_IsCharAlphaNumeric(), STR_IsCharPunct(), STR_IsCharSpace(), STR_IsCharPrint(), STR_IsCharDigit(), STR_IsCharGraph().

STR_IsDigitOrDecimalSeparator() : Determines if characters of the specified string are digits or decimal separator (".").

SyntaxSTR_IsDigitOrDecimalSeparator( szString[,nStart[,nLength]] ) lResult

ParametersszString string to process.nStart specifies the position in the character string from where the string must be processed. Optional. If

not mentioned, the string is processed from the first position (1).nLength specifies the number of characters to process. Optional. If not mentioned, the string is processed

from the starting position to the end of the string.

ReturnslResult are all characters digits and/or decimal separators ('.')? .T. if yes, .F. if not.

Example? STR_IsDigit( "101.8" ) && .F.? STR_IsDigitOrDecimalSeparator( "101.8" ) && .T.

See alsoSTR_IsUpper(), STR_IsCharLower(), STR_IsCharUpper(), STR_IsCharAlpha(), STR_IsCharAlphaNumeric(), STR_IsCharPunct(), STR_IsCharSpace(), STR_IsCharPrint(), STR_IsCharDigit(), STR_IsCharGraph().

String FunctionsSTR_IsInSet() : Determines if characters of the specified string belongs to a set of characters.

AliasIsInSet(), InSet()

SyntaxSTR_IsInSet( szString,szCharacters[,nStart[,nLength]] ) lResult

ParametersszString string to process.szCharacters characters that must be taken in account.nStart specifies the position in the character string from where the string is going to be processed.



ReturnslResult are all the examined characters belonging to the cCharacters set of characters? .T. if yes,

.F. if not.

Example? STR_IsInSet( " –123.18"," +-0123456789." ) && .T.

See alsoSTR_IsUpper(), STR_IsCharLower(), STR_IsCharUpper(), STR_IsCharAlpha(), STR_IsCharAlphaNumeric(), STR_IsCharPunct(), STR_IsCharSpace(), STR_IsCharPrint(), STR_IsCharGraph().

STR_IsNumber() : Determines if a string forms a number.

SyntaxSTR_IsNumber( szString ) lIsNumber


ReturnslIsNumber .T. if szString can be evaluated to a number; .F. if not.

Example? STR_IsNumber( "45" ) && .T.? STR_IsNumber( "45a" ) && .F.? STR_IsNumber( "45+12" ) && .T.? STR_IsNumber( "45-12" ) && .T.

STR_IsLower() : Determines if characters of the specified string are lowercase characters.

Remark

Unlike the ISLOWER() function of Visual FoxPro which only considers the first character, this makes it possible to examine a part of a string. The developer can mention a position from where he wants to process the string, and additionally he can mention a number of characters to process.

String FunctionsSyntaxSTR_IsLower( szString[,nStart[,nLength]] ) lResult




ReturnslResult are all the examined characters in a lowercase format? .T. if yes, .F. if not.

Example? STR_IsLower( "Hello" ) && .F.? STR_IsLower( "Hello",2 ) && .T.? STR_IsLower( "HelLo",2,2 ) && .T.

See alsoSTR_IsUpper(), STR_IsCharLower(), STR_IsCharUpper(), STR_IsCharAlpha(), STR_IsCharAlphaNumeric(), STR_IsCharPunct(), STR_IsCharSpace(), STR_IsCharPrint(), STR_IsCharGraph().

STR_IsUpper() : Determines if characters of the specified string are uppercase characters.

Remark

Unlike the ISUPPER() function of Visual FoxPro which only considers the first character, this makes it possible to examine a part of a string. The developer can mention a position from where he wants to process the string, and additionally he can mention a number of characters to process.

SyntaxSTR_IsUpper( szString[,nStart[,nLength]] ) lResult




ReturnslResult are all the examined characters in an uppercase format? .T. if yes, .F. if not.

Example? STR_IsUpper( "hELLO" ) && .F.? STR_IsUpper( "hELLO",2 ) && .T.? STR_IsUpper( "hELlo",2,2 ) && .T.? STR_IsUpper( "hELlo",2,3 ) && .F.

See alsoSTR_IsLower(), STR_IsCharLower(), STR_IsCharUpper(), STR_IsCharAlpha(), STR_IsCharAlphaNumeric(), STR_IsCharPunct(), STR_IsCharSpace(), STR_IsCharPrint(), STR_IsCharGraph().

String FunctionsSTR_IsValidCreditCard() : Determines whether a credit card number is correct or not.

SyntaxSTR_IsValidCreditCard( cNumber ) lCorrect

ParameterscNumber credit card number with a maximum of 16 digits (if more, the function may generate illegal

operations). Non digit characters are disregarded.

ReturnslCorrect .T. if the credit card number is valid; .F. if not.

Example? STR_IsValidCreditCard( "6045.4360.3078.4771" ) && .F.

STR_IsXDigit() : Determines if characters of the specified string are hexadecimal digits.

SyntaxSTR_IsXDigit( szString[,nStart[,nLength]] ) lResult




ReturnslResult are all the examined characters hexadecimal digits? .T. if yes, .F. if not.

Example? STR_IsXDigit( "0123456789aBCDEF" ) && .T.? STR_IsXDigit( "0123456789ABCDEF" ) && .T.? STR_IsXDigit( "0123456789ABCDEFG" ) && .F.? STR_IsXDigit( "0123456789ABCDEFG",1,16 ) && .T.

See alsoSTR_IsLower(), STR_IsCharLower(), STR_IsCharUpper(), STR_IsCharAlpha(), STR_IsCharAlphaNumeric(), STR_IsCharPunct(), STR_IsCharSpace(), STR_IsCharPrint(), STR_IsCharGraph(), STR_IsCharXDigit().

STR_keep() : Keeps specified characters from a string.

SyntaxSTR_keep( szString,szCharacters ) szNewString

ParametersszString string to be processed.szCharacters characters to keep in string.

String FunctionsReturnsszNewString resulting string. The function is case sensitive !

Example? STR_keep( "Hello World","lod" ) && "lloold" (Length = 6)

STR_last() : Finds the last character that is not a space.

SyntaxSTR_last( szString ) cChar

ParametersszString string to find the last character from.

ReturnscChar last character that is not a space in szString. The string is processed from left to right.

Example? STR_last( "Hello World" ) && "d"? STR_last( "World " ) && "d"

See alsoSTR_first()

STR_LastVersion() : Returns the file stamp of STR functions.

RemarkThis function helps the developer identifying the last version of a set of functions. Sometimes the global version information of FOCUS.FLL (MIS_major() and MIS_minor()) does not help tracking down the changes in a project. Starting with version 6.0 of FOCUS.FLL, each source file has now an internal date and time stamp.

SyntaxSTR_LastVersion() szLastVersion

ParametersNone.

ReturnsszLastVersion string identifying the last version of the functions set. The string is similar to "C:\Focus\5.0\

STRINGS.C-Mon Oct 19 15:55:22 1998".

STR_Left() : Returns a specified number of characters from a character expression, starting with the leftmost character.

SyntaxSTR_Left( szString[,nCount] ) cResult

ParametersszString string to process.nCount specifies the number of characters returned from the character expression. This parameter is

optional. If nCount is greater than the length of szString, an empty string is returned. If nCount is not specified, only the leftmost character of szString is returned.

String FunctionsReturnscResult the nCount leftmost characters of szString.

Example? STR_Left("Hello" ) && "H"? STR_Left("Hello",4 ) && "Hell"

STR_Length() : Determines the length of a string.

AliasSTR_len(), LENGTH()

SyntaxSTR_Length( szString ) nLength

ParametersszString string of which to determine length.

ReturnsnLength length of the string.

STR_Like() : Strings comparison with wildcards.

RemarkAlthough very similar, the STR_Like() function of FOCUS.FLL is not the same as the native LIKE() function of Visual FoxPro. In many situations, both functions can complete each other. STR_like() is particularly easy to use to parse long documents such as HTML pages or even source code.Please remember that the STR_Like() function is case sensitive by default! If you want to perform comparisons without regard to case, please issue STR_LikeCase( .F. ).

SyntaxSTR_Like( szToLookFor,[@]szToSearch[,nToken[,@nLastMatch[,nStart]]] ) nMatch

ParametersszToLookFor the character expression to look for. Wildcards are permitted (* for any character, ? for a single

character).szToSearch the character expression to search. This parameter can be sent by reference for better

performance (remains unchanged).nToken optional token number (a token is either a "*" or a "?" placeholder).nLastMatch optional last match position (MUST BE PASSED BY REFERENCE).nStart optional starting position.

ReturnsnMatch position where the match ends; 0 if no match is found.

ExampleLOCAL szHTML

&& Example 1m.szHTML = '<HTML><HEADER><TITLE>Hello World' + ; '</TITLE></HEADER><BODY BGCOLOR="#FFFF00">This is the body</BODY></HTML>'

? STR_like("*<BODY>*</BODY>*",m.szHTML,2 ) && returns 0

? STR_like("*<BODY*>*</BODY>*",m.szHTML,2 ) && returns 96 because the end of the match && has been found at that position

&& We just asked the second token (second wildcard) which

String Functions&& is the settings of the BODY tag of the HTML page.&& In this case ' BGCOLOR="#FFFF00"'? STR_LikeGetToken() && BGCOLOR="#FFFF00"

? STR_like("*<BODY*>*</BODY>",m.szHTML,2 ) && returns 0 because no wildcard has && been specified at the end of the string

&& Example 2&& This example searches an entire source code (.PRG) and locates&& Change Control Tags so that they can be documented automatically&& A Change Control tag has the following form:&&&& <cc date="20010520120000" auth="Anurak">&& </cc date="20010520120000">

&& As you can see there is an opening tag, and a closing tag&&LOCAL szCodeLOCAL nStartLOCAL nEndLOCAL nEnd2LOCAL nMatchLOCAL szTokenLOCAL iLOCAL szDateTimeLOCAL szAuthorLOCAL szRefLOCAL szCommentLOCAL nAtLine && Starting lineLOCAL nAtLine2 && Ending line

&& m.szFile is the .PRG file to readm.szCode = FILETOSTR( m.szFile )

&& We won't use this variable but we need it for STR_like()m.nMatch = 0&& Staring position to start searching (STR_like())m.nStart = 1&& Without regard to caseSTR_LikeCase( .F. )

WAIT WINDOW "Parsing the code. Please wait..." NOWAIT

IF ( ! EMPTY( m.szCode ) )

m.n && Process the entire string DO WHILE ( .T. )

&& If we can find the opening tag … where does it end? m.nEnd = STR_Like( [*<cc*date="*"*auth="*"*>*],m.szCode,3,@nMatch,m.nStart )

&& Did we find the opening tag? IF ( m.nEnd != 0 ) && We found it … and because we asked FOCUS to store the 3rd placeholder && we now can simply extract the Date/Time value m.szDateTime = STR_LikeGetToken()

&& That's the line number where we found the opening tag m.nAtLine = STR_AtLine( m.nEnd,m.szCode )

&& Let's get the author name now IF ( STR_Like( [*<cc*date="*"*auth="*"*>*],m.szCode,5,@nMatch,m.nStart ) != 0 ) m.szAuthor = STR_LikeGetToken() ELSE m.szAuthor = "" ENDIF

&& Let's get an optional reference number (in case the Change Control

String Functions && has been assigned such a number) IF ( STR_Like( [*<cc*date="*"*ref="*"*>*],m.szCode,5,@nMatch,m.nStart ) != 0 ) m.szRef = STR_LikeGetToken() ELSE m.szRef = "" ENDIF

&& If we want to be exhaustive, we might as well && extract an optional comment (sounds a good idea) IF ( STR_Like([*<cc*date="*"*comment="*"*>*],m.szCode,5,@nMatch,m.nStart) != 0 ) m.szComment = STR_LikeGetToken() ELSE m.szComment = "" ENDIF

&& Let's remember where the oepning tag was ending … because, && this will be used to continue the scanning of the source code m.nStart = m.nEnd

&& Searching for the closing tag now m.nEnd2 = STR_Like( [*</cc*date="] + m.szDateTime + ; [*>*],m.szCode,3,@nMatch,m.nEnd )

&& If we found it IF ( m.nEnd2 != 0 ) && To which line of the source code this tag belongs to? m.nAtLine2 = STR_AtLine( m.nEnd2,m.szCode ) ELSE m.nAtLine2 = -1 ENDIF

&& Imagine we put what we found in a list control && OK, ok … we don't use the reference number nor do && we use the comment! But this is merely an example, right? .lstCCtrl.AddItem( "CC Author: " + m.szAuthor + " -- " + ; "Date : " + m.szDateTime + " -- " + ; "Start:" + ALLTRIM( STR( m.nAtLine ) ) + " ... " + ; "End:" + ALLTRIM( STR( m.nAtLine2 ) ) ; ) ELSE && No opening tag found => we can exit the routine EXIT ENDIF

ENDDO

ENDIF

WAIT WINDOW "Done!" NOWAIT

STR_LikeCase() : Indicates whether STR_Like() should be case sensitive or not (Get/Set function).

RemarkBy default, STR_Like()is case sensitive! You can switch this off via the STR_LikeCase() function.

SyntaxSTR_LikeCase( [lSetting] ) lOldSetting

ParameterslSetting the new setting for STR_Like(). This parameter is optional. If not passed, the function simply

returns the current setting.

String FunctionsReturnslOldSetting old setting.

ExampleLOCAL szHTML

m.szHTML = '<HTML><HEADER><TITLE>Hello World' + ; '</TITLE></HEADER><BODY BGCOLOR="#FFFF00">This is the body</BODY></HTML>'

STR_LikeCase( .T. ) && Should be case sensitive? STR_like("*<body*>*</BODY>*",m.szHTML,2 ) && returns 0STR_LikeCase( .F. ) && Without regard to case? STR_like("*<body*>*</BODY>*",m.szHTML,2 ) && returns 96

STR_LikeGetToken() : Returns the last token specified when using STR_Like().

RemarkThis function can only be used AFTER a first call to STR_Like().

SyntaxSTR_LikeGetToken() szToken

ParametersNone.

ReturnsszToken the specified token or an empty string is this token hasn't been found.

ExampleLOCAL szHTML

m.szHTML = '<HTML><HEADER><TITLE>Hello World' + ; '</TITLE></HEADER><BODY BGCOLOR="#FFFF00">This is the body</BODY></HTML>'

? STR_like("*<BODY>*</BODY>*",m.szHTML,2 ) && returns 0

? STR_like("*<BODY*>*</BODY>*",m.szHTML,2 ) && returns 96 because the end of the match && has been found at that position

&& We just asked the second token (second wildcard) which&& is the settings of the BODY tag of the HTML page.&& In this case ' BGCOLOR="#FFFF00"'? STR_LikeGetToken() && BGCOLOR="#FFFF00"

? STR_like("*<BODY*>*</BODY>",m.szHTML,2 ) && returns 0 because no wildcard has && been specified at the end of the string

STR_ltrim() : Returns the specified character expression with leading blanks removed.

SyntaxSTR_ltrim( szString ) szNewString


String FunctionsReturnsszNewString string with leading blanks removed.

ExampleLOCAl szString

m.szString = " Hello World "

? STR_ltrim( m.szString ) == LTRIM( m.szString ) && .T.

See AlsoSTR_TrimLeft(), STR_TrimRight()

STR_mirror() : Reverses a string.

SyntaxSTR_mirror( szString ) szgnirtS


ReturnsszgnirtS string mirrored.

Example? STR_mirror( "Hello" ) && "olleH"

STR_MixUp() : Mix up a string.

SyntaxSTR_MixUp( szString ) szMixUp


ReturnsszMixUp the string mixed up. STR_MixUp() can be successfully applied on its return value to retrieve the

original string. STR_MixUp(), when combined to other string functions of FOCUS.FLL, can be used to encrypt strings.

Example? STR_MixUp("Hello" ) && "leHlo"

String = "Hello World. Is everybody OK?"encrypted = STR_MixUp( STR_shl( STR_mirror( STR_AddCod( string,3 ) ),4 ) )decrypted = STR_AddCod( STR_mirror( STR_shl( STR_MixUp( encrypted ),-4 ) ),-3 )? ( String == decrypted ) && .T.? encrypted && "å$7&wÆW‡VÇ–d7‚Âv3÷¢%W7öö&„´? decrypted && "Hello World. Is everybody OK?"? LEN( encrypted ) && 29? LEN( decrypted ) && 29

STR_n() : Extracts the nth character of a string.

RemarkThis function is almost identical to STR_peek() but returns a character while STR_peek() returns a numeric.

String FunctionsSyntaxSTR_n( szString,n ) cChar

ParametersszString string to extract the nth character from.n string offset.

ReturnscChar character that was extracted from szString. The first character has order 1.

Example? STR_n( "Hello World",7 ) && "W"

See alsoSTR_last(), STR_first()

STR_nparam() : Extracts the nth parameter of a string.

RemarkThis function is useful when you need to parse strings that are used in Data Driven Applications.

SyntaxSTR_nparam( szString,n ) szParam

ParametersszString string to extract the nth parameter from.n parameter number.

ReturnsszParam character that was extracted from szString. The first character has order 1.

Example? STR_nparam( "MyFunc(15,YourFunc(10,11,12),20",1 ) && "15"? STR_nparam( "MyFunc(15,YourFunc(10,11,12),20",2 ) && "YourFunc(10,11,12)"? STR_nparam( "MyFunc(15,YourFunc(10,11,12),20",2 ) && "20"

STR_npbrk() : Finds the 1st occurrence in a string of any character from another string. Numeric result.

SyntaxSTR_npbrk( szString1,szString2 ) nPosition

ParametersszString1 string to be search for.szString2 string to look for characters.

ReturnsnPosition position of 1st occurrence of a character of szString2 in szString1

Example? STR_npbrk( "The 3 men and 2 dogs ate 5 pigs","0123456789" ) && 5

String FunctionsSTR_nset() : Set first n characters of string to specified character.

AliasSTRNSET()

SyntaxSTR_nset( szString,cChar,n[,x] ) szNewString

ParametersszString string to process (cannot contain embedded nulls CHR(0)).cChar character setting.n number of characters to be set. If n is greater than the length of szString, the length of

szString is used instead of n.x optional starting position.

ReturnsszNewString altered string.

Example&& Example 1? STR_nset( "Hello World","B",4 ) && "BBBBo World"

&& Example 2str2 = SPACE( 15 )str = REPLICATE( "B",15 )? str && "BBBBBBBBBBBBBBB"? str2 && " "? LEN( str ) && 15? LEN( str2 ) && 15str2 = str_nset( str,"A",3,4 ) && Set 3 characters starting at position 4? str2 && "BBBAAABBBBBBBBB"

STR_ntoken() : Extracts a given token from a string.

CautionStrings with embedded nulls cannot be processed by Token functions.When you attempt to extract a given token, ensure that this token does really exist because no test is made to ensure this from within the C and assembler routines. Trying to access a non existing token can produce unpredictable results.

SyntaxSTR_ntoken( nToken,szString[,nStart] ) szToken

ParametersnToken token number.szString string to process.nStart starting position (optional parameter)

ReturnsszToken desired token.

ExampleLOCAL szOldSepLOCAL szStringLOCAL nTokensLOCAL i

String FunctionsszString = "Hello,Cat,Dog,Horse,Lion" && String to processszOldSep = STR_setsep( "," ) && Set internal sep.nTokens = STR_numtok( szString ) && Number of tokens

&& Let's extract a given token? STR_ntoken( 1,szString ) && "Hello"? STR_ntoken( 4,szString ) && "Horse"

&& Let's extract ALL tokensFOR i = 1 TO nTokens && Process all tokens ? STR_ntoken( i,szString ) && Extract given tokenNEXT

STR_setsep( szOldSep ) && Reset separator

STR_null() : Returns a null string (empty string).

CommentThis function can be used with nested functions to get rid of a return value. See also MIS_true() and MIS_false().

SyntaxSTR_null() ""

ParametersNone.

Returns"" empty string.

STR_numtok() : Determines the number of tokens in a string.

CautionStrings with embedded nulls cannot be processed by Token functions.

AliasNumberOfTokens()

SyntaxSTR_numtok( szString[,nStart] ) nTokens

ParametersszString string to process.nStart starting position (optional parameter)

ReturnsnTokens number of tokens based on the internal separator.


szString = "Hello,Cat,Dog,Horse,Lion" && String to processszOldSep = STR_setsep( "," ) && Set internal sep.nTokens = STR_numtok( szString ) && Number of tokens

&& Let's extract a given token? STR_ntoken( 1,szString ) && "Hello"

String Functions? STR_ntoken( 4,szString ) && "Horse"

&& Let's extract ALL tokensFOR i = 1 TO nTokens && Process all tokens ? STR_ntoken( i,szString ) && Extract given tokenNEXT

STR_setsep( szOldSep ) && Reset separator

STR_occu() : Determines position of nth occurrence of a character in a string.

SyntaxSTR_occu( szString,cChar,nOccurrence ) nPosition

ParametersszString string to process.cChar character to look for.nOccurrence occurrence to pay attention to.

ReturnsnPosition position where the nOccurrence of cChar was found in szString.

STR_peek() : Returns the ASCII code of a given character in a string.

SyntaxSTR_peek( szString,nPosition ) nCode

ParametersszString string to process.nPosition position in string to examine.

ReturnsnCode ASCII code value of the character found at nPosition in szString.

Example? STR_peek( "Hello",1 ) && 72 because 'H' is 72

See alsoSTR_n(), STR_poke()

STR_poke() : Poke a character at given position in string.

SyntaxSTR_poke( szString,nPosition,nCode ) szResult

ParametersszString string to process.nPosition position in string to examine.nCode ASCII code to stuff at the proper position.


String FunctionsExampleszString = "Hello"? STR_poke( szString,2,97 ) && "Hallo"? szString && "Hello"

See alsoSTR_peek()

STR_Proper() : Returns a string capitalized appropriately for proper names.

SyntaxSTR_Proper( szString,szSpecialChars ) szProper

ParametersszString string to be processed.szSpecialChars characters that should force an uppercase of the next letter. Usually, these characters are

" ","'",".","-".

ReturnsszProper resulting string.

Potential problemWhen STR_Proper() treats a character string, it cannot distinguish between characters that must be especially kept lowercase as it appears in names such as "Jan de la Court" where "de la" should be especially kept as it is. Therefore, STR_Proper() will use the special character "\" to force an unchanged letter. The way to keep "JAN DE LA COURT" being properly uppercased is to pass the following string "JAN \DE \LA COURT". This is forcing the following result "Jan de la Court".

All characters that are preceded by a backslash are rendered as they appear in the original string.

ExampleLOCAL szName

szName = "Jean-Claude d'Haese"

? STR_Proper( LOWER( szName ) ," -'" ) && "Jean-Claude D'Haese"? STR_Proper( "JEAN-CLAUDE D'HAESE" ," -'" ) && "Jean-Claude D'Haese"? STR_Proper( "JEAN-CLAUDE \d'HAESE"," -'" ) && "Jean-Claude d'Haese"

STR_raw() : Forms a string of characters comprised between a given ASCII range.

RemarkDon't include the CHR(0) in the range of characters to form the raw string. A CHR(0) is treated as the end of the string in C and will therefore not produce the expected result. Should you want to include the CHR(0) char in the set of characters, then simply add it in native FoxPro with a concatenation operation.

The STR_raw() function is really handy to replace strings formed of a character range. For example the STR_raw( 1,5 ) is strictly equivalent to CHR(1)+CHR(2)+CHR(3)+CHR(4)+CHR(5).

SyntaxSTR_raw( nRangeIn,nRangeOut ) szString

ParametersnRangeIn starting range.nRangeOut ending range.

String FunctionsReturnsszString the character string is formed with all the ASCII characters comprised within ASCII nRangeIn and

ASCII nRangeOut.

Example? STR_raw( 1,5 ) == CHR(1)+CHR(2)+CHR(3)+CHR(4)+CHR(5) && .T.

STR_reduce() : Reduces consecutive occurrences of the same character to only 1 occurrence.

SyntaxSTR_reduce( szString,cChar ) szNewString

ParametersszString string to process.cChar character for which reduces consecutive occurrences to only 1 occurrence.


Example? STR_reduce("Hello WWWorld","W" ) // "Hello World"

STR_relin() : Run Encoding Length algorithm (In).

CommentThis function is very useful to compress text files where many occurrences of the same character appear in a consecutive order.

SyntaxSTR_relin( szString ) szNewString



Example? STR_relin( "Hellllllllllo World" )&& The multiple l in "Hellllllllllo World" will be reduced to 3&& characters (first one is CHR(1), second is the number of&& occurrences, third is the character that should be repeated

STR_relout() : Run Encoding Length algorithm (Out).

SyntaxSTR_relout( szString ) szOriString


String FunctionsReturnsszOriString resulting string.

ExampleszString = "Hellllllllllo World"? STR_relout( STR_relin( szString ) ) && "Hellllllllllo World"

STR_Replace() : Replaces a substring with another in a string.

SyntaxSTR_Replace( szString,szExprSought,szReplacement ) szResult

ParametersszString string to process.szExpSought character expression that is searched for in szString. The search is case-sensitive.szReplacement character expression that replaces every occurrence of szExpSought in szString.


ExampleSTR_Replace( "Hello Pat","Pat","Martin" ) && "Hello Martin"

STR_ResetLikeCharConversions() : Resets the conversion table for STR_Like().

RemarkSTR_Like() is capable to match strings for which some loose pattern matching is required. For example, if you want that "Sammy" matches "Fanny", it's enough to state that "S" equals "F" and "m" equals "n". Such character conversions can be specified with STR_SetLikeCharConversion(). When character conversions are no longer needed, the developer can use the STR_ResetLikeCharConversions() to reset the internal table to its original state.

SyntaxSTR_ResetLikeCharConversions() .T.

ParametersNone.

Returns.T. the function returns always .T..

Example? STR_Like( "*Sammy*","Fanny was here." ) && 0

STR_SetLikeCharConversion( "S","F" )STR_SetLikeCharConversion( "m","n" )

? STR_Like( "*Sammy*","Fanny was here." ) && 5

STR_ResetLikeCharConversions()


String FunctionsSTR_Right() : Returns a specified number of characters from a character expression, starting with the rightmost character.

SyntaxSTR_Right( szString[,nCount] ) szResult

ParametersszString string to process.nCount specifies the number of characters returned from the character expression. This parameter is

optional. If nCount is greater than the length of szString, an empty string is returned. If nCount is not specified, only the rightmost character of szString is returned.

ReturnsszResult the nCount rightmost characters of szString.

Example? STR_Right("Hello" ) && "o"? STR_Right("Hello",4 ) && "ello"

STR_rtrim() : Returns the specified character expression with trailing blanks removed.

SyntaxSTR_rtrim( szString ) szNewString


ReturnsszNewString string with trailing blanks removed.


m.szString = " Hello World "

? STR_rtrim( m.szString ) == RTRIM( m.szString ) && .T.

STR_SetCharConversion() : Gets/sets a new character conversion for STR_ConvertA2B() and STR_ConvertB2A().

RemarkSTR_SetCharConversion() provides additional flexibility to the STR_SetConvTable() function to issue character conversions.

SyntaxSTR_SetCharConversion( iChar1,iChar2 ) lSuccess

ParametersiChar1 character for which a conversion needs to take place.iChar2 every occurrence of iChar1 should be converted to iChar2.

String FunctionsReturns.T. .T.. if the function is successful; .F. if not.



&& Every 'H' should be turned into a 'W'STR_SetCharConversion( m.iCharH,m.iCharW )



See alsoSTR_ConvertA2B(), STR_ConvertB2A(), STR_SetConvTable().

STR_SetConvTable() : Sets a conversion table for STR_ConvertA2B() and STR_ConvertB2A().

RemarkThe STR_SetConvTable() function can be used in conjunction with the STR_ConvertA2B() and STR_ConvertB2A(). To give additional flexibility, the STR_SetCharConversion() (not to be confused with STR_SetLikeCharConversion()) can be used to adapt a conversion for a single character.All together, these functions permit to convert character strings: a 'A' must be transformed into a 'C', a 'C' into a 'B', a 'B' into a 'A', … It can be used to scramble strings. Likewise, it can be used to issue ASCII to EBCDIC transformations.

SyntaxSTR_SetConvTable( @aConv ) lResult

ParametersaConv a 256 elements array (MUST be passed by reference). Each cell of the array contains the value

that must be applied for the conversion. The position itself (array index) is associated to the character for which a conversion must take place (be careful … position 1 in the array is associated with CHR(0)).

ReturnslResult .T. if function is successful, .F. if not.

ExampleLOCAL ARRAY aConv[256]<Je devrais reprendre l'exemple d'une table de conversion EBCDIC comme dans le conversion.txt>FOR i = 1 TO 256 aConv[i] = <ICI JE DOIS CONTINUER>NEXT

See alsoSTR_ConvertA2B(), STR_ConvertB2A(), STR_SetCharConversion().

String FunctionsSTR_SetLikeCharConversion() : Gets/sets a new character conversion for STR_Like().

RemarkSTR_Like() is capable to match strings for which some loose pattern matching is required. For example, if you want that "Sammy" matches "Fanny", it's enough to state that "S" equals "F" and "m" equals "n". Such character conversions can be specified with STR_SetLikeCharConversion().

SyntaxSTR_SetLikeCharConversion( cChar1,cChar2 ) .T.

ParameterscChar1 character for which a conversion needs to take place.cChar2 every occurrence of cChar1 will be treated as if it was cChar2.

Returns.T. the function returns always .T..

Example? STR_Like( "*Sammy*","Fanny was here." ) && 0

STR_SetLikeCharConversion( "S","F" )STR_SetLikeCharConversion( "m","n" )


STR_setoff() : Sets the internal offset position of token functions.

CommentSTR_setoff() is one of the token functions. This function is intended to be used when accessing one token after another. In this sense, tokens are not reached at random. STR_setoff() posts the internal counter Offset.

SyntaxSTR_setoff( nOffset ) .T.

ParametersnOffset new value to post into the internal counter Offset. Extra caution ... you can easily fool this

function and consequently STR_toknex() will yield unpredictable results.

Returns.T. the function always returns a logical .T.

STR_setsep() : Gets/sets the internal separator for token based functions.


SyntaxSTR_setsep( szSeparators ) szOldSeparators

String FunctionsParametersszSeparators new separators to use. By default the current separators is ",". You can use a multiple

separators such as ",;:.()/".

ReturnsszOldSeparators current separators.


szString = "Hello,Cat,Dog,Horse,Lion" && String to processszOldSep = STR_setsep( "," ) && Set internal sep.nTokens = STR_numtok( szString ) && Number of tokens

? STR_ntoken( 4,szString ) && "Horse"

FOR i = 1 TO nTokens && Process all tokens ? STR_ntoken( i,szString ) && Extract given tokenNEXT

STR_setsep( szOldSep ) && Reset the separator to what it was

STR_shl() : Shifts-Left a string by a given number of bits.

CommentSTR_shl() can be one useful component of an encryption algorithm. STR_shr() is the opposite function and can be used to restore a string to its original value.

SyntaxSTR_shl( szString,nBits ) szNewString

ParametersszString string to be processed.nBits number of bits to shift the string by. Minimum 1 bit, maximum 7 bits. If you pass a negative

number, the function acts as its contrary STR_shr().

ReturnsszNewString shifted string.

STR_shr() : Shifts-Right a string by a given number of bits.

CommentSTR_shr() can be one useful component of an encryption algorithm. STR_shl() is the opposite function and can be used to restore a string to its original value.

SyntaxSTR_shr( szString,nBits ) szNewString

ParametersszString string to be processed.nBits number of bits to shift the string by. Minimum 1 bit, maximum 7 bits. If you pass a negative

number, the function acts as its contrary STR_shl().

ReturnsszNewString shifted string.

String FunctionsSTR_sort() : Sorts all the characters in a string.

CautionStrings with embedded nulls are not supported.

SyntaxSTR_sort( szStr ) szSorted

ParametersszStr string to process.

ReturnsszSorted szStr sorted.

Example? STR_sort( "Hello World" ) && "Hwdellloor"

STR_soundex() : Returns a phonetic key reprsenting a name.

RemarkThe STR_soundex() function of FOCUS.FLL isn't as fast as the native SOUNDEX() function of Visual FoxPro (due to the fact that strings are really recopied with the FoxPro API to C). But it works better for real names as it does not discriminate the first letter of the word. For example, SOUNDEX() is fooled with the following test:

? SOUNDEX( "HULRICH MEYER" ) == SOUNDEX("ULRICH MAIER" ) && .F.? STR_soundex( "HULRICH MEYER" ) == STR_soundex("ULRICH MAIER" ) && .T.

SyntaxSTR_Soundex( szString ) nResult


ReturnsnResult phonetic key representing szString.

Example&& If the name of that terrorist appears in the text, I won't miss it? STR_soundex( "Ousama Bin Ladin" ) == STR_soundex( "Usama Ben Laden" ) && .T.? STR_soundex( "Ousamma BinLadin" ) == STR_soundex( "Usama ben Laten" ) && .T.

STR_start() : Does a string start with a given value?

SyntaxSTR_start( szString1,szString2 ) lResult

ParametersszString1 string to process.szString2 string to look for.

ReturnslResult .T. if szString1 starts with szString2.

String FunctionsExample? STR_start( "L'Année du dragon","L'" ) && .T.

See alsoSTR_end()

STR_strip() : Strips characters in a given range from a character string.

SyntaxSTR_strip( szString,nRangeIn,nRangeOut ) szNewString

ParametersszString string to process.nRangeIn starting range.nRangeOut ending range.

ReturnsszNewString szString without any character comprised within ASCII nRangeIn and ASCII nRangeOut.

Example? STR_strip( szString,0,31 ) && Eliminates all chars between ASCII 0 and 31

STR_strtok() : Extracts a token from a string.

SyntaxSTR_strtok( n,szString,szSeparators ) szToken

Parametersn token number.szString string to process.szSeparators string of separators.

ReturnsszToken extracted token.

Example? STR_strtok( 1,"Hello World"," " ) && "Hello"

See alsoSTR_end()

STR_TillNull() : Returns a string up to the first null character.

SyntaxSTR_TillNull( szString ) szResult

ParametersszString the string to process. Usually this strings contains null characters.

ReturnsszResult the stripped string. The function does not strip all null characters. It merely returns a substring up

to the first null of szString.

String FunctionsExampleLOCAL szString

szString = REPLICATE( CHR(0),20 )

szString = "Hello" + szString

? STR_TillNull( szString ) && "Hello", all CHR(0) are stripped !

STR_tokfin() : Did we process the entire string?


CommentSTR_tokfin() is one of the token functions. This function is intended to be used to know if we processed entirely a string with STR_toknex().

SyntaxSTR_tokfin() lEnd

ParametersNone.

ReturnslEnd indicates whether we processed the entire token string.

ExampleLOCAL szStringLOCAL szToken

szString = "Hello all of you. Are you OK? What's your name? Mine is Pat"STR_setsep( " .,;?" ) && Separators to be consideredSTR_tokini( szString ) && Initialize the string

CLEAR

? "Begin>>>" && Show when we start

DO WHILE ( ! STR_tokfin() ) && While not end of processing szToken = STR_toknex() && Extract the token IF ( ! EMPTY( szToken ) ) && If the token is not empty ? szToken && Let's display it ENDIFENDDO

? "<<<End" && Show when we end

See AlsoSTR_tokini(), STR_toknex().

STR_tokini() : Initializes internal counters for token processing.

CommentSTR_tokini() is one of the token functions. This function is intended to be used when accessing one token after another. In this sense, tokens are not reached at random. STR_tokini() initializes the internal counters. IT MUST BE USED prior to any SCR_toknex() function call.

String FunctionsSyntaxSTR_tokini( szString ) .T.

ParametersszString the string to be processed.

Returns.T. the function always returns a logical .T.



CLEAR


DO WHILE ( ! STR_tokfin() ) && While not end of processing szToken = STR_toknex() && Extract the token IF ( ! EMPTY( szToken ) ) && If the token is not empty ? szToken && Let's display it ENDIFENDDO


See AlsoSTR_tokfin(), STR_toknex().

STR_toknex() : Gets the next token.

CommentSTR_toknex() is the chore function of optimized token functions. It uses the internal separator.

SyntaxSTR_toknex( szString ) szToken

ParametersszString string from which the next token has to be extracted.

ReturnsszToken next token available in stream.



CLEAR


DO WHILE ( ! STR_tokfin() ) && While not end of processing szToken = STR_toknex() && Extract the token

String Functions IF ( ! EMPTY( szToken ) ) && If the token is not empty ? szToken && Let's display it ENDIFENDDO


See AlsoSTR_tokini(), STR_tokfin().

STR_tokpos() : Determines the starting position of a given token.

SyntaxSTR_tokpos( nToken,szString ) nPosition

ParametersnToken token number.szString string to process.

ReturnsnPosition starting position of the given token.

ExampleLOCAL cOldSepLOCAL szString

szString = "Cat,Dog,Horse,Lion" && String to processcOldSep = STR_setsep( "," ) && Set separator to ","

? STR_tokpos( 4,szString ) && 15

STR_setsep( cOldSep )

CautionWhen you attempt to determine the starting position of a given token, ensure that this token does really exist because no test is made to ensure this from within the C and assembler routines. Trying to access a non existing token can produce unpredictable results.

STR_TrimLeft() : Trims off x characters from the left of a string.

SyntaxSTR_TrimLeft ( szString,n ) szNewString

ParametersszString string to process.n characters count.

ReturnsszNewString output string.


m.szString = "ABCDE"

String Functions? STR_TrimLeft( "ABCDE",1 ) && "BCDE"

See AlsoSTR_LTrim(), STR_RTrim(), STR_TrimRight()

STR_TrimRight() : Trims off x characters from the right of a string.

SyntaxSTR_TrimRight ( szString,n ) szNewString

ParametersszString string to process.n characters count.

ReturnsszNewString output string.


m.szString = "ABCDE"

? STR_TrimRight( "ABCDE",1 ) && "ABCD"

See AlsoSTR_LTrim(), STR_RTrim(), STR_TrimRight()

53 String Functions - Deutschsprachige FoxPro User...

Documents

Transcript of 53 String Functions - Deutschsprachige FoxPro User...