Using TDesC8 Class

Use TDescC8 for interfaces which takes binary data or explicit narrow text, regardless of the build variant, but which does not need to change the data.

Using in a function interface

Interfaces which take binary data or narrow text, use descriptors in the specification of that interface. 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.

Extract leftmost part of data

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.

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

This call to Left() returns a non-modifiable pointer descriptor representing the data string "abcdefg", i.e. the whole content of the descriptor str; this has length 7.

Note that the following call to Left() results in a panic.

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

Extract rightmost part of data

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.

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

This call to Right() returns a non-modifiable pointer descriptor representing the data string "abcdefg", i.e. the whole content of the descriptor str; this has length 7.

Note that the following call to Right() results in a panic.

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

Extract middle portion of the data

The code fragment shows how a portion of data within a descriptor can be accessed, using the TDesC8::Mid() member function. Each call toMid() 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 withTBufC and TPtrC8 withTPtrC.

_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 !

Comparing data

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

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

_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".

Locating a character

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

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

_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

Finding data

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

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

_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

Pattern matching

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

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

_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 '*'.

Referencing a data item

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

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

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

Creating a heap descriptor

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 withTBufC, 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"