Using TDesC8 Class

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

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

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

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

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 with TBufC.

_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 with TBufC, and HBufC8 with HBufC.

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