Using +TDes8 Class

Using in a +function interface

An interface which needs to access and modify +binary data or explicit narrow text, regardless of the build variant, uses +a TDes8 as the argument type. All 8 bit +concrete descriptors are derived from TDes8 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(TDes8& anArg);

The use of TDes8 means that data can be accessed and +modified through the descriptor.

In practice, nearly all code uses +the build independent variant, TDes, unless +an explicit 8 bit or 16 bit build variant is required.

Accessing individual +data items

The code fragment illustrates the use of operator[]().

The +behaviour is the same for the build independent variant, TDes, +replacing _LIT8 with _LIT.

_LIT8(KAtoG,"abcdefg"); +TChar ch; +... +str.Length(); // returns 7 +ch = str[0]; // ch contains the character 'a' +ch = str[3]; // ch contains the character 'd' +... +str[0] = 'z'; // changes str to "zbcdefg" +str[3] = 'z'; // changes str to "abczefg" +... +ch = str[7]; // Panic !! +str[7] = 'z'; // Panic !!_LIT8(KAtoG,"abcdefg");

Copying data

The +code fragment shows the Copy() function.

The +behaviour is the same for the build independent variant, TDes, +replacing _LIT8 with _LIT and TBuf8 with TBuf.

_LIT8(Kabcdefg,"abcdefg"); +_LIT8(Kabc,"abc"); +_LIT8(Kabcdefghi,"abcdefghi"); +... +TBuf8<8> str; +... +str.Copy(Kabcdefg); // copies "abcdefg" to str +str.Length(); // returns 7 +str.MaxLength(); // returns 8 +... +str.Copy(Kabc); // copies "abc" to str +str.Length(); // returns 3 +str.MaxLength(); // returns 8 +... +str.Copy(Kabcdefghi)); // Panics !! +... +

Copying data +with repetition

The code fragment shows the Repeat() function.

The +behaviour is the same for the build independent variant, TDes, +replacing _LIT8 with _LIT and TBuf8 with TBuf.

_LIT8(Kab,"ab"); +_LIT8(Kabc,"abc"); +_LIT8(Kabcde,"abcde"); +... +TBuf8<8> tgt(8); // length of tgt is the same as the +... // maximum which is 8 +... // following strings generated in tgt +... +tgt.Repeat(Kab); // "abababab" +tgt.Repeat(Kabc); // "abcabcab" +tgt.Repeat(Kabcde); // "abcdeabc" +... +... // changing length to 7 has the +... // following effect +tgt.SetLength(7); +tgt.Repeat(Kab); // "abababa" +tgt.Repeat(Kabc); // "abcabca" +tgt.Repeat(Kabcde); // "abcdeab"

Copying data +and justifying

The code fragments show theJustify() function.

The +behaviour is the same for the build independent variant, TDes, +replacing _LIT8 with _LIT and TBuf8 with TBuf.

_LIT8(Kabc,"abc"); +TBuf8<16> tgt(Kabc); +... +tgt.Justify(_L("xyz"),8,ECenter,'@');

The descriptor tgt has +a maximum length of 16 and initially holds the string "abc". +After the call to Justify(), the content of tgt changes +to "@@xyz@@@".

The content of the source descriptor +is taken to form a field of length 8 which replaces the original content of +the descriptor tgt. The characters "xyz" +are centred within the new field and padded on both sides with the fill character '@'.

Setting +the alignment to ELeft would change the content of tgt to +"xyz@@@@@" while setting the alignment to ERight would +change the content of tgt to "@@@@@xyz"

In +all three cases, the length of the descriptor tgt changes +from 3 to 8.

_LIT8(Kabc,"abc"); +_LIT8(Kxyz,"xyz"); +TBuf8<8> tgt(Kabc); +... +tgt.Justify(Kxyz,9,ECenter,'@');

This call to Justify() panics +because the resulting length of data in tgt exceeds the maximum +length of tgt.

_LIT8(Kabc,"abc"); +_LIT8(KRtoZ,"rstuvwxyz"); +TBuf8<16> tgt(Kabc); +... +tgt.Justify(KRtoZ,8,ECenter,'@');

In this call to Justify(), +the content of tgt changes to "rstuvwxy". +Only eight of the nine characters in the source literal KRtoZ are +copied.

Copying conversion +from signed integer to decimal character

The following code fragment +illustrates the use of Num().

The +behaviour is the same for the build independent variant, TDes, +replacing TBuf8 with TBuf.

TBuf8<16> tgt; +... +TInt numpos(176); +TInt numneg(-176); +.. // generates the following strings: +tgt.Num(numpos); // "176" +tgt.Num(numneg); // "-176"

Copying conversion +from unsigned integer to specified number system

The following +code fragment illustrates the use of Num() and NumUC().

The behaviour is the same for the +build independent variant,TDes, replacing TBuf8 withTBuf.

TBuf8<16> tgt; // generates the following strings: +... +TUint number(170); +... +tgt.Num(number,EBinary); // "10101010" +tgt.Num(number,EOctal); // "252" +tgt.Num(number,EDecimal); // "170" +tgt.Num(number,EHex); // "aa" <-NB hex value in lower case +tgt.NumUC(number,EHex); // "AA" <-NB hex value in UPPER case +tgt.Num(number); // "170" <--EDecimal taken as default

Formatting +text

The following code fragments illustrate the various possibilities +of Format().

The behaviour is the +same for the build independent variant, TDes, +replacing _LIT8 with _LIT and TBuf8 with TBuf.

TBuf8<256> tgt; +... +_LIT8(KFormat1,"[%b %c %d %o %u %x]"); +tgt.Format(KFormat1,65,65,65,65,65,65);//generates: +... //[1000001 A 65 101 65 41] +... +_LIT8(KFormat2,"[%04x]"); // pad char="0", field width=4 +tgt.Format(KFormat2,65); //generates: +... //[0041] +... +_LIT8(KFormat3,"[%4x]"); // pad char=default, field width=4 +tgt.Format(KFormat3,65); //generates: +... //[ 41] +... // Note use of blanks as default pad chars. +... +_LIT8(KFormat4,"[%*x]"); // fixed field width, taken from the arguments list +tgt.Format(KFormat4,4,65); //generates: +... //[ 41] +... +... +_LIT8(KFormat5,"[%+$4d.00 %S]"); // pad char="$", field width=4, right aligned +_LIT8(KOver,"over"); +tgt.Format(KFormat5,65,&KOver); //generates: +... //[$$65.00 over] +... +_LIT8(KFormat6,"[%+4d.00 %S]"); // pad char=default, field width=4 +tgt.Format(KFormat6,65,&KOver); //generates: +... //[ 65.00 over] +... // note no pad char specified, defaults +... // to blank +... +_LIT8(KFormat7,"[% 4d.00 %S]"); // pad char=" ", field width=4, alignment=default +tgt.Format(KFormat7,65,&KOver); //generates: +... //[ 65.00 over] +... // note default right hand alignment and +... // blank pad char +... +_LIT8(KFormat8,"[%+0*S]"); // right aligned, pad char="0", fixed field width +_LIT8(KFred,"fred"); +tgt.Format(KFormat8,10,&KFred); //generates: +... //[000000fred] +... // Note - 10 characters generated +... +_LIT8(KFormat9,"[%=*6x]"); // centre aligned, pad char taken from arguments list, field width=6 +tgt.Format(KFormat9,'*',65); //generates: +... //[**41**] +... +_LIT8(KFormat10,"[%+**d]"); // right aligned, pad char and field width taken from arguments list +tgt.Format(KFormat10,'.',10,(-65)); //generates: +... //[.......-65] +... +_LIT8(KFormat11,"[%-A4p]"); // left aligned, field width=4, pad char="A" +tgt.Format(KFormat11,65); //generates: +... //[AAAA] +... // and makes no use of the argument list +... +_LIT8(KFormat12,"[%m]"); //generates: +tgt.Format(KFormat12,4660); // the char '[' +... // followed by a byte with 0x12 +... // followed by a byte with 0x34 +... // followed by the char ']' +_LIT8(KFormat13,"[%M]") +tgt.Format(KFormat13,4660); //generates: +... // the char '[' +... // followed by a byte with 0x00 +... // followed by a byte with 0x00 +... // followed by a byte with 0x12 +... // followed by a byte with 0x34 +... // followed by the char ']' +... +_LIT8(KFormat14,"[%w]"); //generates: +tgt.Format(KFormat14,4660); // the char '[' +... // followed by a byte with 0x34 +... // followed by a byte with 0x12 +... // followed by the char ']' +.. +_LIT8(KFormat15,"[%w]"); //generates: +tgt.Format(KFormat15,4660); // the char '[' +... // followed by a byte with 0x34 +... // followed by a byte with 0x12 +... // followed by a byte with 0x00 +... // followed by a byte with 0x00 +... // followed by the char ']' +... +_LIT8(KFormat16,"[%6.2e]"); +tgt.Format(KFormat16,3.4555); //generates: +... //[3.46E+00] +_LIT8(KFormat17,"[%6.2f]"); +tgt.Format(KFormat17,3.4555); //generates: +... //[ 3.46] +_LIT8(KFormat18,"[%6.2g]"); +tgt.Format(KFormat18,3.4555); //generates: +... //[3.4555] +... +// Variable argument positions +_LIT8(KFormat19,"[%d %d]"); // implicit ordering +tgt.Format(KFormat19,9,5); // generates: +... // [9 5] +... +_LIT8(KFormat20,"[%$2$d %$1$d]"); // explicit ordering +tgt.Format(KFormat20,9,5); // generates: +... // [5 9] +... +_LIT8(KFormat21,"[%$1$d %$2$d]"); // explicit ordering (same as the implicit order) +tgt.Format(KFormat21,9,5); // generates: +... // [9 5] + +// Using argument blocks (a many-to-one mapping between arguments and conversion specifiers) +_LIT8(KFormat22,"[%0*d %d %d]"); // implicit ordering +tgt.Format(KFormat22,3,9,5,12); // generates: +... // [009 5 12] +... +_LIT8(KFormat23,"[%$2$d %$1$0*d %d]"); // mixed explicit and implicit ordering +tgt.Format(KFormat23,3,9,5,12); // generates: +... // [5 009 12] +... +_LIT8(KFormat24,"[%$3$d %$1$0*d %$2$d]"); // explicit ordering +tgt.Format(KFormat24,3,9,5,12); // generates: +... // [12 009 5] + + + +

Inserting data

The +code fragment shows the Insert() function.

The +behaviour is the same for the build independent variant, TDes, +replacing _LIT8 with _LIT and TBuf8 with TBuf.

_LIT8(Kabc,"abc") +_LIT8(KUVWXYZ,"UVWXYZ") +_LIT8(KVWXYZ,"VWXYZ") +_LIT8(KWXYZ,"WXYZ") +_LIT8(KXYZ,"XYZ) +... +TBuf8<8> tgt(3); +... // generates the strings: +tgt = Kabc; +tgt.Insert(0,kXYZ); // "XYZabc" +... +tgt = Kabc; +tgt.Insert(1,KXYZ); // "aXYZbc" +... +tgt = Kabc; +tgt.Insert(tgt.Length(),KXYZ); // "abcXYZ" +... +tgt = Kabc; +tgt.Insert(tgt.Length()+1,KXYZ); // ----> Panic !! +... +tgt = Kabc; +tgt.Insert(1,KWXYZ); // "aWXYZbc" +... +tgt = Kabc; +tgt.Insert(1,KVWXYZ); // "aVWXYZbc" +... +tgt = Kabc; +tgt.Insert(1,KUVWXYZ); // ----> Panic !!

Replacing data

The +following code fragment illustrates the use of Replace().

The +behaviour is the same for the build independent variant, TDes, +replacing _LIT8 with _LIT and TBuf8 with TBuf.

_LIT8(Kabcd,"abcd"); +_LIT8(Ku,"u"); +_LIT8(Kuv,"uv"); +_LIT8(Kuvw,"uvw"); +_LIT8(Kuvwxyz,"uvwxyz"); +... +TBuf8<8> tgt(4); +... // generates the strings: +tgt = Kabcd; +tgt.Replace(0,1,Ku)); // "ubcd" +... +tgt = Kabcd; +tgt.Replace(0,1,Kuv); // "uvbcd" +... +tgt = Kabcd; +tgt.Replace(0,1,Kuvw); // "uvwbcd" +... +tgt = Kabcd; +tgt.Replace(0,1,Kuvwxyz); // ----> Panics !! +... +tgt = Kabcd; +tgt.Replace(1,2,Ku); // "aud" +... +tgt = Kabcd; +tgt.Replace(1,2,KNullDesC8);// "ad" +... +tgt = Kabcd; +tgt.Replace(1,4,Kuvw); // ----> Panics !! +... +tgt = Kabcd; +tgt.Replace(3,1,Kuvw); // "abcuvw" +... +tgt = Kabcd; +tgt.Replace(4,0,Kuvw); // "abcduvw"

Swapping data

This +code fragment shows the Swap() function.

The +behaviour is the same for the build independent variant, TDes, +replacing _LIT8 with _LIT and TBuf8 with TBuf.

_LIT8(Kabcde,"abcde"); +_LIT8(Kxyz,"xyz"); +_LIT8(K0to9,"0123456789"); +... +TBuf8<8> buf1(Kabcde); +TBuf8<8> buf2(Kxyz); +TBuf8<16> buf3(K0to9); +... +buf1.Swap(buf2); // contents of buf1 and buf2 swapped OK +buf1.Swap(buf3); // Panic !!

Deleting data

The +following code fragment illustrates the use of Delete().

The +behaviour is the same for the build independent variant, TDes, +replacing _LIT8 with _LIT and TBuf8 with TBuf.

_LIT8(Kabcd,"abcd"); +... +TBuf8<8> tgt(4); +... // generates the strings: +tgt = Kabcd; +tgt.Delete(0,1); // "bcd" +... +tgt = Kabcd; +tgt.Delete(0,2); // "cd" +... +tgt = Kabcd; +tgt.Delete(0,4); // "" +... +tgt = Kabcd; +tgt.Delete(1,2); // "ad" +... +tgt = Kabcd; +tgt.Delete(2,2); // "ab" +... +tgt = Kabcd; +tgt.Delete(2,3); // "ab" +... +tgt = Kabcd; +tgt.Delete(2,256); // "ab" +... +tgt = Kabcd; +tgt.Delete(5,1); // ----> Panics !! +... +tgt = Kabcd; +tgt.Delete(-1,1); // ----> Panics !!

Deleting leading +spaces

The following code fragment illustrates the use of TrimLeft().

The behaviour is the same for +the build independent variant, TDes, replacing _LIT8 with _LIT and TBuf8 with TBuf.

_LIT8(KData1," abcd "); +_LIT8(KData2," a b "); +... +TBuf8<8> str1(KData1); +TBuf8<8> str2(KData2); +... +str1.Length(); // returns 8 +str1.TrimLeft(); // "abcd " +str1.Length(); // returns 6 +... +str2.Length(); // returns 5 +str2.TrimLeft(); // "a b " +str2.Length(); // returns 4

Deleting trailing +spaces

The following code fragment illustrates the use of TrimRight().

The behaviour is the same for +the build independent variant, TDes, replacing _LIT8 with _LIT and TBuf8 with TBuf.

_LIT8(KData1," abcd "); +_LIT8(KData2," a b "); +... +TBuf8<8> str1(KData1); +TBuf8<8> str2(KData2); +... +str1.Length(); // returns 8 +str1.TrimRight(); // " abcd" +str1.Length(); // returns 6 +... +str2.Length(); // returns 5 +str2.TrimRight(); // " a b" +str2.Length(); // returns 4

Deleting leading +and trailing spaces

The following code fragment illustrates the +use of Trim().

The behaviour is the +same for the build independent variant, TDes, +replacing _LIT8 with _LIT and TBuf8 with TBuf.

_LIT8(KData1," abcd "); +_LIT8(KData2," a b "); +... +TBuf8<8> str1(KData1); +TBuf8<8> str2(KData2); +... +str1.Length(); // returns 8 +str1.Trim(); // "abcd" +str1.Length(); // returns 4 +... +str2.Length(); // returns 5 +str2.Trim(); // "a b" +str2.Length(); // returns 3

Deleting leading, +trailing and internal spaces

The following code fragment illustrates +the use of TrimAll().

The behaviour +is the same for the build independent variant, TDes, +replacing _LIT8 with _LIT and TBuf8 with TBuf.

_LIT8(KData1," abcd "); +_LIT8(KData2," a b "); +_LIT8(KData3,"a b c"); +... +TBuf8<8> str1(KData1); +TBuf8<8> str2(KData2); +TBuf8<8> str2(KData3); +... +str1.Length(); // returns 8 +str1.TrimAll(); // "abcd" +str1.Length(); // returns 4 +... +str2.Length(); // returns 5 +str2.TrimAll(); // "a b" +str2.Length(); // returns 3 +... +str3.Length(); // returns 8 +str3.TrimAll(); // "a b c" +str3.Length(); // returns 5

Append and +justify

The following code fragments illustrate the use of AppendJustify().

The behaviour is the same +for the build independent variant, TDes, +replacing _LIT8 with _LIT and TBuf8 with TBuf.

_LIT8(Kabc,"abc"); +_LIT8(Kxyz, "xyz"); +... +TBuf8<16> tgt(Kabc); +tgt.AppendJustify(Kxyz,8,ECenter,'@');

The descriptor tgt has +a maximum length of 16 and initially holds the string "abc". +After the call to AppendJustify(), the content of tgt changes +to "abc@@xyz@@@".

The content of the source descriptor Kxyz is +taken to form a field of length 8 which is appended to the content of the +descriptor tgt. The characters "xyz" are +centred within the new field and padded on both sides with the fill character '@'.

Setting +the alignment to ELeft would change the content of tgt to +"abcxyz@@@@@" while setting the alignment to ERight would +change the content of tgt to "abc@@@@@xyz".

In +all three cases, the length of the descriptor tgt changes +from 3 to 11.

_LIT8(KAtoK,"abcdefghik"); +_LIT8(K0to6,"0123456"); +... +TBuf8<16> tgt(KAtoK); +tgt.AppendJustify(K0to6,7,ECenter,'@');

This call to AppendJustify() panics +because the resulting length of tgt exceeds its maximum length.

Append and +justify with explicit length

The following code fragments illustrate +the use of the overloaded version of AppendJustify() which +specifies an explicit length.

The behaviour is the same for the build +independent variant,TDes, replacing _LIT8 with _LIT and TBuf8 with TBuf.

_LIT8(Kabc,"abc"); +_LIT8(Kxyz0to9,"xyz0123456789"); +... +TBuf8<16> tgt(Kabc); +tgt.AppendJustify(Kxyz0to9,3,8,ECenter,'@');

The descriptor tgt has +a maximum length of 16 and initially holds the string "abc". +After the call to AppendJustify(), the content of tgt changes +to "abc@@xyz@@@".

In this example, the first three +characters of the eleven characters "xyz0123456789" are taken to form an eight +character field which is appended to the existing content of the descriptor tgt. +The three characters "xyz" are centred within the new field +and padded on both sides with the fill character '@'.

Setting +the alignment to ELeft would change the content of tgt to +"abcxyz@@@@@" while setting the alignment to ERight would +change the content of tgt to "abc@@@@@xyz".

In +all three cases, the length of the descriptor tgt changes +from 3 to 11.

_LIT8(Kabc,"abc"); +_LIT8(K0to9,"0123456789"); +... +TBuf8<16> tgt(Kabc); +tgt.AppendJustify(K0to9,9,8,ECenter,'@');

In this example, +the call to AppendJustify() changes the content of tgt to +"abc01234567". As the specified length is greater than the +specified width, the length is truncated so that only eight characters are +copied from the source descriptor.

_LIT8(KAtoK,"abcdefghik"); +_LIT8(K0to9,"0123456789"); +... +TBuf8<16> tgt(KAtoK); +tgt.AppendJustify(K0to9,3,7,ECenter,'@');

This call to AppendJustify() panics +because the resulting length of tgt exceeds its maximum length.

Append data +operator

The following code fragment illustrates the use of operator+=().

_LIT8(Kabc,"abc"); +TBuf8<16> tgt(Kabc); +... +tgt+=(_L("0123456789")); // generates "abc0123456789" +tgt+=(_L("0123456789qwerty")); // Panics !!

Append conversion +from signed integer to decimal character

The following code fragment +illustrates the use of AppendNum().

The +behaviour is the same for the build independent variant, TDes, +replacing TBuf8 with TBuf.

_LIT8(Kabc,"abc"); +TInt numpos(176); +TInt numneg(-176); +... +TBuf8<16> tgt(Kabc)); // generates the following strings: +tgt.AppendNum(numpos); // "abc176" +tgt.AppendNum(numneg); // "abc-176"

Append conversion +from unsigned integer to specified number system

The following +code fragment illustrates the use of AppendNum() andAppendNumUC().

The behaviour is the same for +the build independent variant, TDes, replacing _LIT8 with _LIT and TBuf8 with TBuf.

_LIT8(Kabc,"abc"); +TBuf8<16> tgt(Kabc); // generates the following strings: +... +TUint num(170); +... +tgt.AppendNum(num,EBinary); // "abc10101010" +tgt.AppendNum(num,EOctal); // "abc252" +tgt.AppendNum(num,EDecimal);// "abc170" +tgt.AppendNum(num,EHex); // "abcaa" <-hex value in lower case +tgt.AppendNumUC(num,EHex); // "abcAA" <-hex value in UPPER case +tgt.AppendNum(num); // "abc170" <-EDecimal taken as default

Append fixed +width conversion

The following code fragment illustrates the use +of AppendNumFixedWidth() and AppendNumFixedWidthUC().

The +behaviour is the same for the build independent variant, TDes, +replacing _LIT8 with _LIT and TBuf8 with TBuf.

_LIT8(Kabc,"abc"); +TBuf8<16> tgt(Kabc); // generates the following strings: +... +TUint num(170) +... +tgt.AppendNumFixedWidth(num,EBinary,8); // "abc10101010" +tgt.AppendNumFixedWidth(num,EOctal,8); // "abc00000252" +tgt.AppendNumFixedWidth(num,EDecimal,8); // "abc00000170" +tgt.AppendNumFixedWidth(num,EHex,8); // "abc000000aa" +tgt.AppendNumFixedWidthUC(num,EHex,8); // "abc000000AA"