How to +use the non-modifiable buffer descriptor

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