CHRTRAN(), STRTRAN(), STUFF(), Sys(15), Sys(20)

Hacker’s Guide to Visual FoxPro
An irreverent look at how Visual FoxPro really works. Tells you the inside scoop on every command, function, property, event and method of Visual FoxPro.

`CHRTRAN()`, `STRTRAN()`, `STUFF()`, Sys(15), Sys(20)

These five methods of manipulating strings are great for translation and some cool effects.

Usage

cRetVal = CHRTRAN( cSource, cCharsToReplace, cReplacements )
cRetVal = STRTRAN( cSource, cStringToReplace
                   [, cReplacementString
                   [, nStartOccurrence
                   [, nHowMany
                   [, nFlags ] ] ] ])
cRetVal = STUFF( cSource, nWhereToStart, nLong,
                  cReplacementString )
cRetVal = SYS( 15, cSource, cTransTable )
cRetVal = SYS( 20, cSource, nLength )

Parameter	Value	Meaning
cSource	Character	The original string to be manipulated.
cCharsToReplace	Character	The individual characters to be replaced.
cReplacements	Character	The new characters to replace those of cCharsToReplace, mapped one-to-one to the originals.
cStringToReplace	Character	The exact string to locate and replace in cSource.
cReplacementString	Character	The new string to be substituted for cStringToReplace.
cReplacementString	Omitted	cStringToReplace is cut from the text.
nStartOccurrence	Numeric	Optionally specify at which occurrence the replacement starts.
nStartOccurrence	Omitted	Replacement starts at the first occurrence.
nHowMany	Numeric	How many of the occurrences to replace.
nHowMany	Omitted	All occurrences are replaced.
nFlags	0 or 2	Perform a case-sensitive search. If cStringToReplace is found, replace it with cReplacementString in its current case.
	1	Perform a case-insensitive search. If cStringToReplace is found, replace it with cReplacementString in its current case.
	3	Perform a case-insensitive search. If cStringToReplace is found, replace it with cReplacementString, matching the case of cStringToReplace as much as possible.
nWhereToStart	Numeric	Starting location for string replacement.
nLong	Numeric	Number of characters to be discarded from the original string.
nLong	0	Preserve all existing characters while inserting new text.
cTransTable	Character	A string of up to 255 characters; replaces original characters based on position in string and ASCII value of original.
nLength	Numeric	The number of characters of cSource to process.

CHRTRAN() and SYS(15) are search-and-replace functions that operate on a single character at a time. Use CHRTRAN() to eliminate or translate one or a few characters, and SYS(15) if you need to translate all characters.

STRTRAN() is a similar search-and-replace function for entire words and phrases at one time. Use STRTRAN() to replace one word or phrase with another. In VFP 7, STRTRAN() has the ability to search and replace without regard to the case of the strings involved. The search can pay attention to case or not. If you do a case-insensitive search, you have the option of making the replacement string’s case match that of the string it’s replacing. Use –1 for nStartOccurrence and nHowMany to skip those parameters and specify nFlags. (The –1 value indicates that the default values for those parameters should be used. We think it would be nice if there were a constant in FoxPro.H for this.)

STUFF() is more of an insert function, optionally either overwriting existing characters or pushing them out of the way as it inserts new text. STUFF() may be more efficient at combining character strings than the + append operator, depending on the environment in which you are running and the tasks you must perform.

SYS(15) and SYS(20) were originally intended as methods of providing indexes to European users. SYS(15) worked by stripping accents from characters. SYS(20) worked by creating a longer string with binary values that would create a proper German phonebook order. SET COLLATE does a far better job of properly weighting these characters, rather than discarding them, and therefore should be used instead. However, SYS(15) does provide a universal translation mechanism that can be useful for other purposes, as shown in the last example below.

Example

? CHRTRAN("ABCDE", "ACE", "XYZ")           && yields "XBYDZ"
? CHRTRAN("ABCDE", "ACE", "")              && yields "BD"
? CHRTRAN("ABCDE", "ACE", "X")             && yields "XBD"
? STRTRAN("The brown fox", "brown", "red") && "The red fox"
? STRTRAN("1a2a3a4a5a6a7a", 'a', 'b', 3, 2)  && "1a2a3b4b5a6a7a"
? STRTRAN("RED, Red, red", "red", "blue")
   && yields "RED, Red, blue"
? STRTRAN("RED, Red, red", "red", "blue", -1, -1, 1)
   && yields "blue, blue, blue"
? STRTRAN("RED, Red, red", "red", "blue", -1, -1, 3)
   && yields "BLUE, Blue, blue"
? STUFF("5 pound sack", 1, 7, "10 pounds of potatoes in")
* results in "10 pounds of potatoes in sack"

In the first example, CHRTRAN() is used to replace the characters A, C and E with X, Y and Z, respectively. In the second example, a blank string of replacements leads to the elimination of all letters listed as the second parameter. In the third example, a combination of the two above is shown, where X is substituted for A, and C and E are eliminated completely.

The next group of examples shows the word-replacement capabilities of STRTRAN(). The first example performs a straight substitution of one word for another. The second example in the group replaces only specified occurrences within the source string. The last three STRTRAN() examples show the behavior of the new nFlags parameter.

Finally, the last example shows the STUFF() function in action, inserting and replacing portions of a string.

Here’s an example of the power of SYS(15), an example we’ve found helpful when we discover we’ve left the CAPS LOCK on after a few pages of witty prose:

* Invert - return string with case reversed
LPARAMETER tcString
LOCAL i, cTransStr  && counter and string
cTransStr = ""
FOR i = 1 TO 255
  DO CASE
    CASE NOT ISALPHA(CHR(I))  && not a letter - don't change!
      cTransStr = cTransStr + CHR(i)
    CASE ISLOWER(CHR(I))    && lower case
      cTransStr = cTransStr + UPPER(CHR(i))
    CASE ISUPPER(CHR(I))    && upper case
      cTransStr = cTransStr + LOWER(CHR(i))
  ENDCASE
NEXT
RETURN SYS(15,cTransStr,tcString)

Applying this function to any block of text returns the original string, but with all uppercase characters changed to lower and all lowercase changed to upper.