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.