How to -use the non-modifiable buffer descriptor

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

- -Literal Descriptors - + + + + + +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();

+ +Literal Descriptors

\ No newline at end of file