Wiki Home

STRTRANEX ()& WORDTRANEX ()


Namespace: WIN_COM_API
STRTRANEX() and WORDTRANEX() are the functions from St_Denis library.

STRTRANEX () a user-defined function with enhanced search-and-replace capabilities as compared to the built-in FoxPro function STRTRAN().


STRTRANEX() Searches a string for the strings that are elements of the second parameter and replaces each occurrence with a corresponding element of the third parameter.

STRTRANEX (cSearched, cArExpressionSought | cExpressionSough, [cArReplacement | cReplacement][, nArStartOccurrence | nStartOccurrence] [, nArNumberOfOccurrences | nNumberOfOccurrences] [, nArFlags | nFlags], [ArReport])
Return Values String

WORDTRANEX() a user-defined function with enhanced search-and-replace capabilities as compared to the function WORDTRAN().

WORDTRANEX() Searches a string for the words that are elements of the second parameter and replaces each occurrence with a corresponding element of the third parameter.


WORDTRANEX (cSearched, cArExpressionSought | cExpressionSough, [cArReplacement | cReplacement] [, cDelimiters] [, nArStartOccurrence | nStartOccurrence] [, nArNumberOfOccurrences | nNumberOfOccurrences] [, nArFlags | nFlags], [ArReport])
Return Values String

In contrast with the function STRTRANEX(), the function WORDTRANEX() searches for words rather than strings. Consequently, the function WORDTRANEX() accepts an additional parameter which is a string of word delimiters.


Parameters
cSearched Specifies the character expression that is searched.

cArExpressionSought| cExpressionSought Specifies the array of the string or cExpressionSought specifies string, each string of the array is searched for in cSearched.
If the second parameter is the string cExpressionSought rather than an array, this function behaves identically to the built-in function STRTRAN().

cArReplacement| cReplacement The array of strings cArReplacement or the string cReplacement is used to replace within cSearched every occurrence of the corresponding strings specified in cArExpressionSought.
If the parameter cArReplacement is omitted, every occurrence of each string specified in cArExpressionSought is replaced with an empty string.
If cArReplacement has more rows than cArExpressionSought, the extra rows within the array cArExpressionSought are ignored.
If cArReplacement has less rows than cArExpressionSought, the extra rows within the array cArExpressionSought are replaced with an empty string.
If the third parameter is the string cReplacement rather than an array, each occurrence of each row of the array cArExpressionSought is replaced with cReplacement.


cDelimiters (only for the WORDTRANEX() function) Specifies one or more optional characters used to separate words in cSearched. The default delimiters are space, tab, carriage return, and line feed. The maximum length of cDelimiters is 256.
Note that WORDTRANEX () uses each of the characters in cDelimiters as individual delimiters, not the entire string as a single delimiter.


nArStartOccurrence| nStartOccurrence Each row of the array of numbers nArStartOccurrence or the number nStartOccurrence specifies the number of the occurrence of the corresponding row of the array cArExpressionSought which is the first to be replaced.
If nArStartOccurrence has more rows than cArExpressionSought, the extra rows within nArStartOccurrence are ignored.
If nArStartOccurrence has less rows than cArExpressionSought, the extra rows of cArExpressionSought are replaced starting from the first occurrence.
If the fourth (the fifth in the case of the function WORDTRANEX()) parameter is the number nStartOccurrence rather than an array, each occurrence of each row of the array cArExpressionSought is replaced starting from the occurrence specified in nStartOccurrence.
For example, if nStartOccurrence is 4, the replacements start from the fourth occurrence of cExpressionSought in cSearched, and the first three occurrences of cExpressionSought in cSearched remain unchanged.
As another example, consider the case when the first row of the array nArStartOccurrence is 4. Then, the replacement begins with the fourth occurrence within cSearched of the first row of the array cArExpressionSought, and the first three occurrences within cSearched of the first row of the array cArExpressionSought remain unchanged.
If the parameter nArStartOccurrence is -1 or omitted, the replacement starts with the first occurrence of cExpressionSought.


nArNumberOfOccurrences | nNumberOfOccurrences The numeric array nArNumberOfOccurrences or the number nNumberOfOccurrences specifies the number of occurrences of the rows from cArExpressionSought to replace within cSearched.
If nArNumberOfOccurrences or nNumberOfOccurrences is omitted, all occurrences of each row of cArExpressionSought are replaced, starting from the occurrence specified with nArNumberOfOccurrences or nStartOccurrence.
If nArNumberOfOccurrences has more rows than cArExpressionSought, the extra rows within cArReplacement are ignored.
If nArNumberOfOccurrences has less rows than cArExpressionSought, the occurrences of the extra rows of cArExpressionSought are replaced, starting from the occurrence number specified with nArNumberOfOccurrences or nStartOccurrence.
In the case when the fifth (the sixth in the case of the function WORDTRANEX()) parameter is a number nNumberOfOccurrences rather than an array, each occurrence of each row of cArExpressionSought is replaced nNumberOfOccurrence times, starting from the occurrence number specified with nArNumberOfOccurrences or nStartOccurrence.

nArFlags | nFlags The numeric array nArFlags or the number nFlags specifies the case-sensitivity of the search according to the following values:

nFlags or a row of the array nArFlags Description
0 (default) Search is case-sensitive, replace is with exact string to replace.
1 Search is case-insensitive, replace is with exact string to replace.
2 Search is case-sensitive; replace is with the case of the string to replace, the string changed to match the case of the string found. The case of the string to replace will only be changed if the string found is all uppercase, lowercase, or proper case.
3 Search is case-insensitive; replace is with the case of the string to replace, the string changed to match the case of the string found. The case of the string to replace will only be changed if the string found is all uppercase, lowercase, or proper case.
-

If nArFlags has more rows than cArExpressionSought, the extra rows of nArFlags are ignored.
If nArFlags has less rows than cArExpressionSought, all occurrences of the extra rows of cArExpressionSought are replaced using default case sensitivity.
If the sixth (the seventh in the case of the function WORDTRANEX()) parameter is a number nFlags rather than an array, each occurrence of each row of cArExpressionSought is replaced according to nFlags.

ArReport The parameter ArReport, which is of the character type, specifies the name of a global two-dimensional array created by the function.
This array consists of three columns of the numeric type.
The first column contains the starting position within cSearched of a substring or word that was found.
The second column contains the number of the row within cArExpressionSought which identifies the substring that was found.
The third column contains a flag that indicates the case of the substring that replaced the found substring.
The flag can assume the following values:
0, if the case of the substring has not been changed.
1, if the substring was converted to the upper case.
2, if the substring was converted to the lowercase.
3, if the first letter of the substring was capitalized, and the remaining letters of the substring were converted to the lower case.

To summarize, the array ArReport contains the status information about the work done by the function STRTRANEX() or WORDTRANEX().
The number of rows in ArRepor equals the number of the found and replaced substrings.
If nothing has been found, the array ArReport is not created.

Remarks
You can specify where the replacement begins and how many replacements are made for each row of the array cArExpressionSought .
If you omit cReplacement, every occurrence of cExpressionSought is replaced with the empty string.
The occurrence where replacement begins defaults to the first occurrence of cExpressionSought if you omit nStartOccurrence.
If you omit nNumberOfOccurrences, all occurrences of cExpressionSought, starting with the occurrence specified with nStartOccurrence, are replaced.
Specify -1 for optional parameters you want to skip over if you just need to specify the nFlags setting.



STRTRANEX (cSearched, cExpressionSough, cReplacement, nStartOccurrence, nNumberOfOccurrences, nFlags) returns the same result as
STRTRAN (cSearched, cExpressionSough, cReplacement, nStartOccurrence, nNumberOfOccurrences, nFlags)

This function is able to replace, for example, the string A with the string B and, at the same time, to replace the string B with the string A. In other words, this function is able to exchange the positions of substrings within a string. Several substrings can be replaced or deleted in a single pass.

Igor Nikiforov is an author of the functions.

Examples:
Set Library To St_Denis Additive

Clear
Local lcStr1, lcStr2, lcStr3 ,lcStr4
Local Array ArExpressionSought(1), ArReplacement(1), ArStartOccurrence(1), ArNumberOfOccurrences(1), ArFlags(1)

*** In this example, the built-in function Strtran and the function StrtranEx perform equivalently but StrtranEx generates a report on the work done.
lcStr1 = "The fifth of the Twelve Labours set to Heracles was to clean the Augean stables in a single day."
Strtran(lcStr1, "ab", "ba", -1, -1, 0)
StrtranEx(lcStr1, "ab", "ba", -1, -1, 0, "gArRapp")
Display Memory Like gArRapp && displays the status information about the work done by the function StrtranEx

Wait

Dimension ArExpressionSought(2), ArReplacement(2), ArStartOccurrence(2), ArNumberOfOccurrences(2), ArFlags(2)

Dimension ArExpressionSought(4), ArReplacement(4)

ArExpressionSought(1) = "ab"
ArExpressionSought(2) = "ly"
ArExpressionSought(3) = "ea"
ArExpressionSought(4) = "as"

*** In this example, StrtranEx replaces all strings from the array ArExpressionSought with a string "ba".
lcStr2 = "The reasoning behind this being set as a labour was twofold: firstly, all the previous labours exalted Heracles in the eyes of the people and this one would surely degrade him;"+;
" secondly, as the livestock were a divine gift to Augeas they were immune from disease and thus the amount of dirt and filth amassed in the uncleaned stables made the task surely impossible."
StrtranEx(lcStr2, @ArExpressionSought, "ba")
Wait
*** In this example, all strings are deleted from the array ArExpressionSought.
StrtranEx(lcStr2, @ArExpressionSought)
Wait

ArReplacement(1) = "1"
ArReplacement(2) = "22"
ArReplacement(3) = "333"
ArReplacement(4) = "4444"

*** In this example, all strings from the array ArExpressionSought are replaced by the corresponding strings from the array ArReplacement. The search is case-insensitive.
StrtranEx(lcStr2, @ArExpressionSought, @ArReplacement, -1, -1, 1)
Wait
*** In this example, the first occurrence of each string from the array ArExpressionSought is replaced by the corresponding string from the array ArReplacement. The search is case-sensitive.
StrtranEx(lcStr2, @ArExpressionSought, @ArReplacement, 1, 1)
Wait
Dimension ArReplacement(2)
*** In this example, all strings from the array ArExpressionSought are replaced with the corresponding strings from the array ArReplacement. The search is case-instensitive. The last two strings from the array ArExpressionSought are deleted because the array ArReplacement has only two elements.
StrtranEx(lcStr2, @ArExpressionSought, @ArReplacement, -1, -1, 1)
Wait

*** In this example, the fifth element of the array ArExpressionSought is not a string. The call to the function StrtranEx results in the error message, "Function argument value, type, or count is invalid (Error 11)".
Local lcSaveError
lcSaveError = On("error")
On Error Messagebox([ArExpressionSought(5) is not of character type !], 0+48, [This is an error "Function argument value, type, or count is invalid (Error 11)"], 10000)
Dimension ArExpressionSought(5)
StrtranEx(lcStr2, @ArExpressionSought, @ArReplacement, -1, -1, 1) && error "Function argument value, type, or count is invalid (Error 11)" because ArExpressionSought(5) is not of character type !
On Error &lcSaveError
Wait

Dimension ArExpressionSought(4)
Dimension ArStartOccurrence(4), ArNumberOfOccurrences(4), ArFlags(4)

ArStartOccurrence(1) = -1
ArStartOccurrence(2) = 1
ArStartOccurrence(3) = 2
ArStartOccurrence(4) = 3

ArNumberOfOccurrences(1) = -1
ArNumberOfOccurrences(2) = 1
ArNumberOfOccurrences(3) = 2
ArNumberOfOccurrences(4) = 3

ArFlags(1) = 0
ArFlags(2) = 1
ArFlags(3) = 2
ArFlags(4) = 3

*** This example shows how to use different search-and-replace criteria for each string from the array ArExpressionSought.
StrtranEx(lcStr2, @ArExpressionSought, @ArReplacement, @ArStartOccurrence, @ArNumberOfOccurrences, @ArFlags, "gArRapp")
Display Memory Like gArRapp && displays the status information about the work done by the function StrtranEx

Wait

Dimension ArExpressionSought(6), ArReplacement(6)
ArExpressionSought(1) = "A"
ArExpressionSought(2) = "THIS"
ArExpressionSought(3) = "to"
ArExpressionSought(4) = "As"
ArExpressionSought(5) = "Augeas"
ArExpressionSought(6) = "was"

ArReplacement(1) = "a"
ArReplacement(2) = "that"
ArReplacement(3) = "into"
ArReplacement(4) = " as "
ArReplacement(5) = " Midas "
ArReplacement(6) = "were"

*** This example shows how to use the function WordtranEx with different search-and-replace criteria for each word from the array ArExpressionSought
WordtranEx(lcStr2, @ArExpressionSought, @ArReplacement, [ ,.!;:"]+Chr(13)+Chr(10), @ArStartOccurrence, @ArNumberOfOccurrences, @ArFlags, "gArRapp")
Display Memory Like gArRapp && displays the status information about the work done by the function WordtranEx
Wait

*** In this example, the function WordtranEx works as a filter, leaving only one occurrence of each word from the array ArExpressionSought
WordtranEx(lcStr2, @ArExpressionSought, "", [ ,.!;:"]+Chr(13)+Chr(10), 2, -1, 1)
Wait

Dimension ArExpressionSought(2), ArReplacement(2)

ArExpressionSought(1) = "damocles"
ArExpressionSought(2) = "dionysius"

ArReplacement(1) = "heracles"
ArReplacement(2) = "augeas"


lcStr3 = "Dionysius was irate because he had promised Damocles one-tenth of his cattle if the job was finished in one day."
*** This example shows how to replace all words from the array ArExpressionSought with the corresponding words from the array ArReplacement. The search is case-insensitive
WordtranEx(lcStr3, @ArExpressionSought, @ArReplacement, [ ,.!;:"]+Chr(13)+Chr(10), -1, -1, 3, "gArRapp")
Display Memory Like gArRapp && displays the status information about the work done by the function WordtranEx
Wait

Dimension ArExpressionSought(4), ArFlags(4)
Dimension ArReplacement(3)
ArExpressionSought(3) = "he"
ArExpressionSought(4) = "was"

ArReplacement(3) = "she"

ArFlags(1) = 3
ArFlags(2) = 3
ArFlags(3) = 0
ArFlags(4) = 2
*** This example shows how to use different search-and-replace criteria to replace all words from the array ArExpressionSought with the corresponding words from the array ArReplacement. The search is case-insensitive.
WordtranEx(lcStr3, @ArExpressionSought, @ArReplacement, [ ,.!;:"]+Chr(13)+Chr(10), -1, -1, @ArFlags, "gArRapp")

Display Memory Like gArRapp && displays the status information about the work done by the function WordtranEx
Wait

*** This example shows how to interchange the word "Phyleus" with the word "Augeas".
lcStr4 = "He refused to honour the agreement, and Heracles killed him after completing the tasks and gave his kingdom to Phyleus' son, Augeas, who had been exiled for supporting Heracles against his father."
StrInversion(lcStr4, "Phyleus", "Augeas")

** This function is able to replace, for example, the string A with the string B and,
** at the same time, to replace the string B with the string A. In other words,
** this function is able to exchange the positions of substrings within a string.
Function StrInversion
Lparameters tStr, tArStr1, tArStr2
External Array tArStr1, tArStr2
Local lnI, lnJ, lnR
Local Array lArr1(1), lArr2(1)
If Type("tStr") <> "C"
tStr = Transform(tStr)
Endif
If Type("tArStr1", 1) = "A"
lnR = Min(Alen(tArStr1, 1), Iif(Type("tArStr2", 1) = "A", Alen(tArStr2, 1), 1))
Dimension lArr1(lnR * 2)
Dimension lArr2(lnR * 2)
For lnI = 1 To lnR
lArr1(lnI * 2 - 1) = Iif(Alen(tArStr1, 2) = 0, tArStr1(lnI), tArStr1(lnI, 1))
If Type("lArr1(lnI * 2 - 1)") <> "C"
lArr1(lnI * 2 - 1) = Transform( lArr1(lnI * 2 - 1))
Endif
lArr2(lnI * 2) = lArr1(lnI * 2 - 1)
Endfor
Else
lnR = 1
If Type("tArStr1") <> "C"
tArStr1 = Transform(tArStr1)
Endif
Dimension lArr1(2)
Dimension lArr2(2)
lArr1(1) = tArStr1
lArr2(2) = tArStr1
Endif

If Type("tArStr2", 1) = "A"
For lnI = 1 To lnR
lArr2(lnI * 2 - 1) = Iif(Alen(tArStr2, 2) = 0, tArStr2(lnI), tArStr2(lnI, 1))
If Type("lArr2(lnI * 2 - 1)") <> "C"
lArr2(lnI * 2 - 1) = Transform( lArr2(lnI * 2 - 1))
Endif
lArr1(lnI * 2) = lArr2(lnI * 2 - 1)
Endfor
Else
If Type("tArStr2") <> "C"
tArStr2 = Transform(tArStr2)
Endif
lArr1(2) = tArStr2
lArr2(1) = tArStr2
Endif

Return StrtranEx(tStr, @lArr1, @lArr2)


Sometimes the function StrtranEx has a better performance than the built-in function Strtran
Local lnS, lcStrT, lcSearch1, lcRepl
lnS = Seconds()
lcSearch1 = "ab"
lcRepl = "ba"
lcStrT = Replicate( lcSearch1 + Replicate("cd", 2**7), 2**12)
r1=Strtran(lcStrT , lcSearch1, lcRepl, -1, -1, 0)
?[ Strtran ], Len(lcStrT ), Seconds() - lnS, [ seconds]

lnS = Seconds()
r2=StrtranEx(lcStrT , lcSearch1, lcRepl, -1, -1, 0)
?[ StrtranEx ], Len(lcStrT ), Seconds() - lnS, [ seconds]
( Topic last updated: 2009.08.31 10:18:23 AM )