Using TDesC16 Class

Interfaces which take wide (Unicode) text, use descriptors in the specification of that interface.

An interface which needs access to Unicode text, regardless of the build variant, but which does not need to change that data in any way, uses a TDesC16 as the argument type. 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.

• Using TDesC in a function interface

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.

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

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

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

_LIT16(KData,"abcdefg");
TBufC16<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 TDesC16::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 _LIT16 with _LIT, TBufC16withTBufC and TPtrC16with 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 !

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

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

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

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

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

_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

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

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

_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

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

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

_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 ‘*’.

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

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

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

The behaviour is the same for the build independent variant,TDesC, replacing _LIT16 with _LIT, TBufC16withTBufC and HBufC16with 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"