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