Using TDesC8 Class

Interfaces which take binary data or narrow text, use descriptors in the specification of that interface.

An interface which needs access to binary data or explicit narrow text, regardless of the build variant, but which does not need to change that data in any way, uses a TDesC8 as the argument type. All 8 bit concrete descriptors are derived from TDesC8 which means that the interface can accept any 8 bit descriptor.

The following code fragment shows the most common function prototype pattern.

void ClassX::foo(const TDesC8& anArg);

The use of TDesC8 ensures that the data cannot be modified through the descriptor; const is an extra guarantee that the data cannot be changed.

In practice, nearly all code uses the build independent variant, TDesC, unless an explicit 8 bit or 16 bit build variant is required.

• Using TDesC in a function interface

The code fragment shows how the leftmost part of data in a descriptor can be accessed, using the TDesC8::Left() member function.

The behaviour is the same for the build independent variant, TDesC, replacing _LIT8 with _LIT, TBufC8 with TBufC and TPtrC8 with TPtrC.

_LIT8(KData,"abcdefg");
TBufC8<8> str(KData);
...
str.Left(4);

The call to Left() returns a non-modifiable pointer descriptor representing the data string "abcd"; this has length 4. The original data contained in, and represented by, the non modifiable buffer descriptor str, is not changed in any way.

Note that the following calls to Left() result in a panic.

_LIT8(KData,"abcdefg");
TBufC8<8> str(KData);
...
str.Left(8); // Panic !
str.Left(-1); // Panic !

The code fragment shows how the rightmost part of data in a descriptor can be accessed, using the TDesC8::Right() member function.

The behaviour is the same for the build independent variant, TDesC, replacing _LIT8 with _LIT, TBufC8 with TBufC and TPtrC8 with TPtrC.

_LIT8(KData,"abcdefg");
TBufC8<8> str(KData);
...
str.Right(4);

The call to Right() returns a non-modifiable pointer descriptor representing the data string "defg"; this has length 4. The original data contained in, and represented by, the non modifiable buffer descriptor str, is not changed in any way.

Note that the following calls to Right() result in a panic.

_LIT8(KData,"abcdefg");
TBufC8<8> str(KData);
...
str.Right(8); // Panic !
str.Right(-1); // Panic !

The code fragment shows how a portion of data within a descriptor can be accessed, using the TDesC8::Mid() member function. Each call to Mid() returns a non-modifiable pointer descriptor representing the selected portions of data.

The behaviour is the same for the build independent variant, TDesC, replacing _LIT8 with _LIT, TBufC8 with TBufC and TPtrC8 with TPtrC.

_LIT8(KData,"abcdefg");
TBufC8 str(KData);
...
str.Mid(0); //returns TPtrC8 representing "abcdefg"; length is 7
str.Mid(1); //returns TPtrC8 representing "bcdefg"; length is 6
str.Mid(6); //returns TPtrC8 representing "g"; length is 1
str.Mid(3,3); //returns TPtrC8 representing "def"; length is 3
str.Mid(0,7); //returns TPtrC8 representing "abcdefg"; length is 7
...
str.Mid(8); // Panics !
str.Mid(3,5); // Panics !

This code fragment shows the TDesC8::Compare() function.

The behaviour is the same for the build independent variant, TDesC, replacing _LIT8 with _LIT, TBufC8 with TBufC.

_LIT8(Kabcd, "abcd");
_LIT8(Kabcde, "abcde");
_LIT8(Kabc, "abc");
_LIT8(Kabcx, "abcx");
...
TBufC8<8> str(Kabcd);
...
str.Compare(Kabcde); // returns -ve
str.Compare(Kabc); // returns +ve
str.Compare(Kabcd); // returns zero
str.Compare(Kabcx); // returns -ve

This result of the comparison means that:

• "abcd" is less than "abcde".

• "abcd" is greater than "abc".

• "abcd" is equal to "abcd".

• "abcd" is less than "abcx".

This code fragment shows the TDesC8::Locate() function.

The behaviour is the same for the build independent variant, TDesC, replacing _LIT8 with _LIT, TBufC8 with TBufC.

_LIT8(Kabcd,"abcd");
TBufC8<8> str(Kabcd);
...
str.Locate('d'); // returns 3
str.Locate('a'); // returns 0
str.Locate('b'); // returns 1
str.Locate('x'); // returns KErrNotFound

This code fragment shows the TDesC8::Find() function.

The behaviour is the same for the build independent variant, TDesC, replacing _LIT8 with _LIT, TBufC8 with TBufC.

_LIT8(KAtoZ,"abcdefghijklmnopqrstuvwxyz");
TBufC8<32> str(KAtoZ);
...
_LIT8(KFind1,"abc");
str.Find(KFind1); // returns 0

_LIT8(KFInd2,"bcde");
str.Find(KFInd2); // returns 1

_LIT8(KFind3,"uvwxyz");
str.Find(KFind3); // returns 20

_LIT8(KFind4,"0123");
str.Find(KFind4); // returns KErrNotFound

_LIT8(KFind5,"abcdefghijklmnopqrstuvwxyz01");
str.Find(KFind5); // returns KErrNotFound

str.Find(KNullDesC8); // returns 0

This code fragment shows the TDesC8::Match() function.

The behaviour is the same for the build independent variant, TDesC, replacing _LIT8 with _LIT, TBufC8 with TBufC.

_LIT8(KAtoZ,"abcdefghijklmnopqrstuvwxyz");
TBufC8<32> str(KAtoZ);
    ...
_LIT8(KMatch1,"*ijk*");
str.Match(KMatch1); //returns -> 8

_LIT8(KMatch2,"*i?k*");
str.Match(KMatch2); // -> 8

_LIT8(KMatch3,"ijk*");
str.Match(KMatch3); // -> KErrNotFound

_LIT8(KMatch4,"abcd");
str.Match(KMatch4); // -> KErrNotFound

_LIT8(KMatch5,"*i*mn*");
str.Match(KMatch5); // -> 8

_LIT8(KMatch6,"abcdef*");
str.Match(KMatch6); // -> 0

_LIT8(KMatch7,"*");
str.Match(KMatch7); // -> 0

_LIT8(KMatch8,"*y*");
str.Match(KMatch8); // -> 24

_lit8(KMatch9,"*i??k*");
str.Match(KMatch9); // -> KErrNotFound

To test for the existence of a pattern within a text string, the pattern must start and end with an '*'.

The code fragment shows how a data item can be referenced using operator[]().

The behaviour is the same for the build independent variant, TDesC, replacing _LIT8 with _LIT, TBufC8 with TBufC.

_LIT8(KData,"abcdefg");
TBufC8<8> str(KData);
...
str[0]; // returns reference to 'a'
str[3]; // returns reference to 'd'
str[7]; // Panics !!

The code fragments show how a heap descriptor is created from an existing descriptor using the TDesC8::AllocL() member function.

The behaviour is the same for the build independent variant, TDesC, replacing _LIT8 with _LIT, TBufC8 with TBufC, andHBufC8 withHBufC.

_LIT8(KData,"abcdefg");
TBufC8<16> str(KData);
...
HBufC8* ptr;
...
ptr = str.AllocL(); //Creates and returns address of
... //heap descriptor. The new heap descriptor
... //contains a copy of the original data.
ptr->Length(); //Returns 7; the length of "abcdfeg"