Using -TDesC8 Class

diff -r ebc84c812384 -r 46218c8b8afa Symbian3/PDK/Source/GUID-FD273259-2282-5353-847D-853D483C37BC.dita --- a/Symbian3/PDK/Source/GUID-FD273259-2282-5353-847D-853D483C37BC.dita Thu Mar 11 15:24:26 2010 +0000 +++ b/Symbian3/PDK/Source/GUID-FD273259-2282-5353-847D-853D483C37BC.dita Thu Mar 11 18:02:22 2010 +0000 @@ -1,202 +1,202 @@ - - - - - -Using -TDesC8 ClassUse 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"

- -Using TDesC in a function interface - + + + + + +Using +TDesC8 ClassUse 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"

+ +Using TDesC in a function interface +

\ No newline at end of file