How to -use the modifiable pointer descriptor

How to -use the modifiable pointer descriptor — TPtrModifiable 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.

- -Literal Descriptors - + + + + + +How to use the modifiable pointer descriptor — TPtrModifiable 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.

+Literal +Descriptors

\ No newline at end of file