Using TDesC16 Class

Using in a function interface

Interfaces which take wide (Unicode) text, use descriptors in the specification of that interface. All 16 bit concrete descriptors are derived from TDesC16 which means that the interface can accept any 16 bit descriptor.

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

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

The use of TDesC16 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 form, 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 TDesC16::Left() member function.

The behaviour is the same for the build independent variant, TDesC, replacing _LIT16 with _LIT, TBufC16 with TBufC and TPtrC16 with TPtrC.

_LIT16(KData,"abcdefg");
TBufC16<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.

_LIT16(KData,"abcdefg");
TBufC16<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.

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

Extract rightmost part of data

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

The behaviour is the same for the build independent variant, TDesC, replacing _LIT16 with _LIT, TBufC16 with TBufC and TPtrC16 with TPtrC.

_LIT16(KData,"abcdefg");
TBufC16<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.

_LIT16(KData,"abcdefg");
TBufC16<8> str(KData);
...
str.Right(256);

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

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

_LIT16(KData,"abcdefg");
TBufC16<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 TDesC16::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 _LIT16 with _LIT,TBufC16 withTBufC andTPtrC16 with TPtrC.

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

Comparing data

This code fragment shows theTDesC16::Compare() function.

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

_LIT16(Kabcd,  "abcd");
_LIT16(Kabcde, "abcde");
_LIT16(Kabc,   "abc");
_LIT16(Kabcx,  "abcx");
...
TBufC16<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 theTDesC16::Locate() function.

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

_LIT16(Kabcd,"abcd");
TBufC16<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 TDesC16::Find() function.

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

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

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

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

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

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

str.Find(KNullDesC16);       // returns 0

Pattern matching

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

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

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

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

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

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

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

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

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

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

_LIT16(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 usingTDesC16::operator[]().

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

_LIT16(KData,"abcdefg");
TBufC16<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 TDesC16::AllocL() member function.

The behaviour is the same for the build independent variant,TDesC, replacing _LIT16 with _LIT,TBufC16 withTBufC andHBufC16 with HBufC.

_LIT16(KData,"abcdefg");
TBufC16<16> str(KData);
...
HBufC16* 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"