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 after ptr.Zero(), the descriptor
represents no data. Nevertheless, the maximum length remains unchanged.