How to -use modifiable buffer descriptor

How to -use modifiable buffer descriptor — TBuf<TInt>Modifiable buffer descriptors are useful for holding strings or -data and providing safe ways to access and modify that data. -

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

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 TBuf<TInt>

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

as an empty buffer descriptor.
as an empty buffer descriptor -but giving it a length.
by copying data from -any other type of descriptor.
by copying data from -another modifiable buffer descriptor of the same size.

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

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

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

The following code fragment -constructs a TBuf<16> object and sets it length to 12. -No data is assigned into the descriptor.

... -TBuf<16> buf1(12); // length of buf1 is 12 -...

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

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

The following code fragment constructs -a TBuf<16> object from another TBuf<16> object. -This is, in effect, copy construction.

_LIT(KText,"Hello World!"); -... -TBuf<16> buf1(KText); -TBuf<16> buf2(buf1); // buf2 constructed from the data in buf1

In -both of these cases, the resulting length of the descriptor is 12.

A -non-modifiable buffer descriptor can also be constructed from 'C' style zero -terminated string. However, this is rarely necessary but may make it easier -to port legacy 'C' code.

Replacing data

Data -within a modifiable buffer descriptor can be completely replaced through the -assignment operator or by using the Copy() function.

_LIT(KText,"Hello World!"); -_LIT(KNewText,"New text"); -_LIT(KReplaced,"Replaced"); -... -TBuf<16> buf1(KText); -TBuf<16> buf2; -... -buf2 = buf1; // buf2 now contains "Hello World!" -... -buf2 = KNewText; // buf2 now contains "New text". - // the literal is converted to a descriptor - // type. -buf2.Copy(KReplaced); // buf2 content replaced using Copy()

Accessing and -changing data

Once a modifiable buffer descriptor has been constructed, -the functions in the base classes, TDesC and TDes, -are available to be access and change the data.

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

and

_LIT(KText,"Hello World!"); -... -TBufC<16> buf1(KText); // length is 12 -... -buf1.Delete(6,6); // length is now 6, leaving "Hello" in - // the buffer

Illegal access -causing an exception

The following code fragment raises a panic -because of an attempt to assign too much data. The maximum length of the buffer -descriptor is 16 but the length of the data to be copied is 31:

_LIT(KText,"Hello World! The sun is shining"); -... -TBufC<16> buf1(KText);

The following code fragment raises -a panic because of an attempt to delete data outside the boundary defined -by the descriptor:

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

- -Literal Descriptors - + + + + + +How to +use modifiable buffer descriptor — TBuf<TInt>Modifiable buffer descriptors are useful for holding strings or +data and providing safe ways to access and modify that data. +

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

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 TBuf<TInt>

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

as an empty buffer descriptor.
as an empty buffer descriptor +but giving it a length.
by copying data from +any other type of descriptor.
by copying data from +another modifiable buffer descriptor of the same size.

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

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

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

The following code fragment +constructs a TBuf<16> object and sets it length to 12. +No data is assigned into the descriptor.

... +TBuf<16> buf1(12); // length of buf1 is 12 +...

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

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

The following code fragment constructs +a TBuf<16> object from another TBuf<16> object. +This is, in effect, copy construction.

_LIT(KText,"Hello World!"); +... +TBuf<16> buf1(KText); +TBuf<16> buf2(buf1); // buf2 constructed from the data in buf1

In +both of these cases, the resulting length of the descriptor is 12.

A +non-modifiable buffer descriptor can also be constructed from 'C' style zero +terminated string. However, this is rarely necessary but may make it easier +to port legacy 'C' code.

Replacing data

Data +within a modifiable buffer descriptor can be completely replaced through the +assignment operator or by using the Copy() function.

_LIT(KText,"Hello World!"); +_LIT(KNewText,"New text"); +_LIT(KReplaced,"Replaced"); +... +TBuf<16> buf1(KText); +TBuf<16> buf2; +... +buf2 = buf1; // buf2 now contains "Hello World!" +... +buf2 = KNewText; // buf2 now contains "New text". + // the literal is converted to a descriptor + // type. +buf2.Copy(KReplaced); // buf2 content replaced using Copy()

Accessing and +changing data

Once a modifiable buffer descriptor has been constructed, +the functions in the base classes, TDesC and TDes, +are available to be access and change the data.

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

and

_LIT(KText,"Hello World!"); +... +TBufC<16> buf1(KText); // length is 12 +... +buf1.Delete(6,6); // length is now 6, leaving "Hello" in + // the buffer

Illegal access +causing an exception

The following code fragment raises a panic +because of an attempt to assign too much data. The maximum length of the buffer +descriptor is 16 but the length of the data to be copied is 31:

_LIT(KText,"Hello World! The sun is shining"); +... +TBufC<16> buf1(KText);

The following code fragment raises +a panic because of an attempt to delete data outside the boundary defined +by the descriptor:

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

+ +Literal Descriptors +

\ No newline at end of file