Introduction String Manipulation There are an abundance of powerful string functions described in this chapter. A high degree of speed is assured because these functions and all of the CA-Clipper Tools are written exclusively in Assembler. We have made an effort to find an appropriate example for as many unusual variations as possible. In view of this, we would like to take this opportunity to clarify a few ground rules regarding the use of these functions. Passing Parameters by Reference This chapter includes functions that pass parameters by reference. The following paragraphs contain clarification about these functions. It has been possible to pass parameters of the character string type by reference to a UDF since the summer of 1987. This means that a reference to the original string is passed, thus avoiding the creation of an internal copy. When a function accepts this type of parameter and changes it, the original string is actually changed. This behavior does not normally apply to CA-Clipper functions. However, some CA-Clipper Tools functions behave differently and take parameters passed by reference. These functions and their corresponding parameters are described as reference sensitive in this section and are identified with [@] in the argument section of each function's description. Passing parameters by reference has advantages and disadvantages. The most important advantage is that memory requirements are reduced. This allows you to avoid runtime errors that could result when there is insufficient memory available for string manipulation. Whether or not the insufficient memory is a disadvantage depends on the function being used. Often you will want to change the original string. In a call that does not pass parameters by reference, the copy changed by the function must then be passed back to the "original" string again: AR := "Hello" VAR := FUNCTION(VAR) When you work with very long strings, this method takes memory and time! Here is an example of the reference method: VAR := "Hello" FUNCTION(@VAR) With most CA-Clipper Tools functions, it doesn't make any sense to pass parameters by reference. In some cases, a result is different when a parameter is passed in this way. However, when you do pass by reference, the functions change the parameters passed by the string directly. Memory is saved, and the functions work more quickly because you no longer need to make an internal copy. Watch for the [@] marker, indicating that a parameter is reference sensitive. Functions which change the length of a string cannot, in principle pass by reference. Here is an overview of the functions that change length, or depending upon usage, could change if you attempt to pass by reference. ATREPL() POSDEL() CHAREVEN() POSINS() CHARODD() POSREPL() CHARONE() WORDONE() CHARONLY() WORDONLY() CHARREM() WORDTOCHAR() CSETREF() This function additionally allows you to significantly optimize reference sensitive functions with regard to execution speed and memory use. Full details can be found in the corresponding function description later in this chapter.