Introduction

     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:

     VAR := "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.