How to use the non-modifiable buffer descriptor — TBufC<TInt>

Non-modifiable buffer descriptors are useful for holding constant strings or data and providing safe ways to access that data.

For text data, it is usual to construct a TBufC<TInt> type and allow the appropriate variant, either a TBufC8<TInt> or a TBufC16<TInt> to be selected at build time.
For binary data, an explicit TBufC8<TInt> is used.
It is rare to use an explicit TBufC16<TInt>.

Data cannot be changed through this descriptor although it can be replaced using the assignment operators.

By using the Des() function to construct a TPtr/TPtr8/TPtr16 modifiable pointer descriptor for the buffer's data, it becomes possible to modify that data.

Although, the following notes refer to the build independent types; they are equally valid for the explicit 8 bit and 16 bit types.

Constructing a TBufC<TInt>

A non-modifiable buffer descriptor can be constructed in a number of ways:

as an empty buffer descriptor.
by copying data from any other type of descriptor.
by copying data from another non-modifiable buffer descriptor of the same size.

The following code fragment constructs a TBufC<16> object. The buffer descriptor is uninitialised, i.e. it contains no data. The assignment operator can be used to put data into the buffer descriptor after construction:

_LIT(KText,"Hello World!");
...
TBufC<16> buf1; // length of buf1 is 0
...
buf1 = KText;   // data assigned

The following code fragment constructs a TBufC<16> object, initialised with the 12 characters making up the English language phrase "Hello World!".

The source descriptor is a literal which is converted to descriptor type.

_LIT(KText,"Hello World!");
...
TBufC<16> buf1(KText);  // length of buf1 is 12

The following code fragment constructs a TBufC<16> object, initialised with the content of another TBufC<16> object.

_LIT(KText,"Hello World!");
...
TBufC<16> buf1(KText);
TBufC<16> buf2(buf1);  // data copied from descriptor buf1
                       // length of buf2 is 12

Replacing data

Data within a non-modifiable buffer descriptor can be completely replaced by using the assignment operator:

_LIT(KText,"Hello World!");
_LIT(KNewText,"New text");
...
TBufC<16> buf1(KText);
TBufC<16> buf2;
...
buf2 = buf1;               // buf2 now contains "Hello World!"
...
buf2 = KNewText;           // buf2 now contains "New text".
                           // the literal is converted to a descriptor
                           // type.

To prevent data replacement, declare buf2 as const.

Constructing a modifiable pointer descriptor to change the data

The data contained in non-modifiable buffer descriptor TBufC<TInt> can be changed by constructing a TPtr modifiable pointer descriptor using theDes() member function and then changing the data through that TPtr.

The maximum length of the TPtr is the value of the TBufC<TInt> template parameter.

The following code fragment shows data being changed:

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

This deletes the last character in buf1 and adds the characters " & Hi" so that buf1 now contains the text "Hello World & Hi" and its length is 16. Note that the length of both buf1 and ptr change to reflect the data that they now both represent.

Note that any attempt to append more data raises a panic.

Accessing data

Once a non-modifiable buffer descriptor has been constructed, the functions in the base class, TDesC, are available to access the data.

_LIT(KText,"Hello World!");
...
TBufC<16> buf1(KText);
...

buf1.Length();

Related concepts

Literal Descriptors