Collapse all Symbian^3 Application Developer Library

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

Replacing data through the TPtr

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

Changing the length of data

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.

Parent topic: How to Use Descriptors

Related concepts

Literal Descriptors