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 .

Constructing a TPtr

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();

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);

Replacing data through the TPtr

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

       _LIT(KText,"Hi there");
ptr = 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).

Changing the length of data

The length of the data represented can be changed.

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

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.

Related concepts
Literal Descriptors