How to use the modifiable pointer descriptor — TPtr

Modifiable pointer descriptors are useful for referencing strings or data which can be accessed and changed.

• For text data, it is usual to construct a TPtr type and allow the appropriate variant, either a TPtr or a TPtrC to be selected at build time.

• For binary data, an explicit TPtr8 is used.

• It is rare to use an explicit TPtr16.

A modifiable pointer descriptor can be constructed in a number of ways:

• another modifiable pointer descriptor.

• from a non-modifiable buffer descriptor using the Des() function

• from an explicit pointer into memory and specifying a maximum length.

• from an explicit pointer into memory and specifying the length of the data and a maximum length.

The following code fragment constructs a TPtr to represent the data already represented by another TPtr:

TPtr ptr1;
...
TPtr ptr2(ptr1);
...

The following code fragment constructs a TPtr for a non-modifiable buffer descriptor, a TBufC<TInt>, using the Des() function. Data that would normally be unmodifiable through the TBufC<TInt> can be changed through the TPtr.

The source are literals which are converted to descriptor type.

_LIT(KText,"Hello World!");
_LIT(KExtraText," & Hi");
...
TBufC<16> buf1(KText);
...
TPtr ptr = buf1.Des();
...
ptr.Delete((ptr.Length()-1),1);
ptr.Append(KExtraText);

Define a TText area initialised to contain the string "Have a nice day":

The following code fragments show the construction of a TPtr using a pointer and specifying a length and a maximum length. This technique is not commonly used. Literals are a much better way of defining string constants.

TText str[16] = {'H', 'a', 'v', 'e', ' ', 'a',
    ' ', 'n', 'i', 'c', 'e',
    ' ', 'd', 'a', 'y', '\0'};

TPtr ptr(&str[0],15,16);

The descriptor ptr represents the data in str and is constructed to have a current length of 15 (the length of the text, excluding the zero terminator) and a maximum length of 16 (the actual length of str). Once the descriptor has been constructed, it has no further use for the zero terminator.

TPtr ptr(&str[0],15,16);

Data can be completely replaced using the assignment operator or the Copy() function.:

_LIT(KText,"Hi there");
...
ptr = KText;
...
ptr.Copy(KText);

Note the use of the _LIT macro to define the source string. A literal is converted into a descriptor type.

The length of ptr is now 8 but the maximum length remains unchanged. The size depends on the build variant. In a non-Unicode build, this is 8 but in a Unicode build, this becomes 16 (two bytes for every character).

The length of the data represented can be changed.

_LIT(KText,"Hi there");
...
ptr = KText;
ptr.SetLength(2);
ptr.Zero();

For example, after ptr.SetLength(2), the descriptor represents the string "Hi". The length can even be set to zero so that afterptr.Zero(), the descriptor represents no data. Nevertheless, the maximum length remains unchanged.

Literal Descriptors