Using TDes16 Class

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

An interface which needs to access and modify Unicode text, regardless of the build variant, uses a TDes16 as the argument type. All 16 bit concrete descriptors are derived from TDes16 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(TDes16& anArg);

The use of TDes16 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.

See also

• Using TDes in a function interface

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

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

_LIT16(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 !!

The code fragment shows the Copy() function.

The behaviour is the same for the build independent variant, TDes, replacing _LIT16 with _LIT, and TBuf16 with TBuf.

_LIT16(Kabcdefg,"abcdefg");
_LIT16(Kabc,"abc");
_LIT16(Kabcdefghi,"abcdefghi");
...
TBuf16<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 !!

The code fragment shows the Repeat() function.

The behaviour is the same for the build independent variant, TDes, replacing _LIT16 with _LIT, and TBuf16 with TBuf.

_LIT16(Kab,"ab");
_LIT16(Kabc,"abc");
_LIT16(Kabcde,"abcde");
...
TBuf16<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"

The code fragments show theJustify()function.

The behaviour is the same for the build independent variant,TDes, replacing _LIT16 with _LIT, and TBuf16with TBuf.

_LIT16(Kabc,"abc");
TBuf16<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 oftgt to "xyz@@@@@" while setting the alignment toERight would change the content of tgt to "@@@@@xyz"

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

_LIT16(Kabc,"abc");
_LIT16(Kxyz,"xyz");
TBuf16<8> tgt(Kabc);
...
tgt.Justify(Kxyz,9,ECenter,'@');

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

_LIT16(Kabc,"abc");
_LIT16(KRtoZ,"rstuvwxyz");
TBuf16<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.

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

The behaviour is the same for the build independent variant,TDes, replacing TBuf16with TBuf.

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

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

The behaviour is the same for the build independent variant,TDes, replacing TBuf16with TBuf.

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

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

The behaviour is the same for the build independent variant,TDes, replacing _LIT16 with _LIT, and TBuf16with TBuf.

TBuf16<256> tgt;
...
_LIT16(KFormat1,"[%b %c %d %o %u %x]");
tgt.Format(KFormat1,65,65,65,65,65,65);//generates:
... //[1000001 A 65 101 65 41]
...
_LIT16(KFormat2,"[%04x]"); //generates:
tgt.Format(KFormat2,65); //[0041]
...
_LIT16(KFormat3,"[%4x]"); //generates:
tgt.Format(KFormat3,65); //[ 41]
... // Note use of blanks as
... // default fill chars.
...
_LIT16(KFormat4,"[%*x]"); //generates:
tgt.Format(KFormat4,4,65); //[ 41]
... // width taken from the
... // argument list
...
_LIT16(KFormat5,"[%+$4d.00 %S]");
_LIT16(KOver,"over"); //generates:
tgt.Format(KFormat5,65,&KOver); //[$$65.00 over]
...
_LIT16(KFormat6,"[%+4d.00 %S]"); //generates:
tgt.Format(KFormat6,65,&KOver); //[ 65.00 over]
... // note no pad char
... // specified, defaults
... // to blank
...
_LIT16(KFormat7,"[% 4d.00 %S]"); //generates:
tgt.Format(KFormat7,65,&KOver); //[ 65.00 over]
... // note default right
... // hand alignment and
... // blank pad char
...
_LIT16(KFormat8,"[%+0*S]");
_LIT16(KFred,"fred"); //generates:
tgt.Format(KFormat8,10,&KFred); //[000000fred]
...
_LIT16(KFormat9,"[%=*6x]"); //generates:
tgt.Format(KFormat9,'*',65); //[**41**]
...
_LIT16(KFormat10,"[%+**d]"); //generates:
tgt.Format(KFormat10,'.',10,(-65)); //[.......-65]
...
_LIT16(KFormat11,"[%-A4p]"); //generates
tgt.Format(KFormat11,65); //[AAAA]
... // and makes no use of
... // the argument list
...
_LIT16(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 ']'
_LIT16(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 ']'
...
_LIT16(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 ']'
..
_LIT16(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 ']'
...
_LIT16(KFormat16,"[%6.2e]"); //generates:
tgt.Format(KFormat16,3.4555); //[3.46E+00]
...
_LIT16(KFormat17,"[%6.2f]"); //generates:
tgt.Format(KFormat17,3.4555); //[ 3.46]
...
_LIT16(KFormat18,"[%6.2g]"); //generates:
tgt.Format(KFormat18,3.4555); //[3.4555]

The code fragment shows the Insert() function.

The behaviour is the same for the build independent variant,TDes, replacing _LIT16 with _LIT, and TBuf16with TBuf.

_LIT16(Kabc,"abc")
_LIT16(KUVWXYZ,"UVWXYZ")
_LIT16(KVWXYZ,"VWXYZ")
_LIT16(KWXYZ,"WXYZ")
_LIT16(KXYZ,"XYZ)
...
TBuf16<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 !!

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

The behaviour is the same for the build independent variant,TDes, replacing _LIT16 with _LIT, and TBuf16with TBuf.

_LIT16(Kabcd,"abcd");
_LIT16(Ku,"u");
_LIT16(Kuv,"uv");
_LIT16(Kuvw,"uvw");
_LIT16(Kuvwxyz,"uvwxyz");
...
TBuf16<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,KNullDesC16);// "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"

This code fragment shows the Swap() function.

The behaviour is the same for the build independent variant,TDes, replacing _LIT16 with _LIT, and TBuf16with TBuf.

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

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

The behaviour is the same for the build independent variant,TDes, replacing _LIT16 with _LIT, and TBuf16with TBuf.

_LIT16(Kabcd,"abcd");
...
TBuf16<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 !!

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

The behaviour is the same for the build independent variant,TDes, replacing _LIT16 with _LIT, and TBuf16with TBuf.

_LIT16(KData1," abcd ");
_LIT16(KData2," a b ");
...
TBuf16<8> str1(KData1);
TBuf16<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

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

The behaviour is the same for the build independent variant,TDes, replacing _LIT16 with _LIT, and TBuf16with TBuf.

_LIT16(KData1," abcd ");
_LIT16(KData2," a b ");
...
TBuf16<8> str1(KData1);
TBuf16<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

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

The behaviour is the same for the build independent variant,TDes, replacing _LIT16 with _LIT, and TBuf16with TBuf.

_LIT16(KData1," abcd ");
_LIT16(KData2," a b ");
...
TBuf16<8> str1(KData1);
TBuf16<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

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

The behaviour is the same for the build independent variant,TDes, replacing _LIT16 with _LIT, and TBuf16with TBuf.

_LIT16(KData1," abcd ");
_LIT16(KData2," a b ");
_LIT16(KData3,"a b c");
...
TBuf16<8> str1(KData1);
TBuf16<8> str2(KData2);
TBuf16<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

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

The behaviour is the same for the build independent variant,TDes, replacing _LIT16 with _LIT, and TBuf16with TBuf.

_LIT16(Kabc,"abc");
_LIT16(Kxyz, "xyz");
...
TBuf16<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 oftgt 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 descriptortgt. 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 oftgt to "abcxyz@@@@@" while setting the alignment toERight would change the content of tgt to "abc@@@@@xyz".

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

_LIT16(KAtoK,"abcdefghik");
_LIT16(K0to6,"0123456");
...
TBuf16<16> tgt(KAtoK);
tgt.AppendJustify(K0to6,7,ECenter,'@');

This call to AppendJustify() panics because the resulting length oftgt exceeds its maximum 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 _LIT16 with _LIT, and TBuf16with TBuf.

_LIT16(Kabc,"abc");
_LIT16(Kxyz0to9,"xyz0123456789");
...
TBuf16<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 oftgt 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 oftgt to "abcxyz@@@@@" while setting the alignment toERight would change the content of tgt to "abc@@@@@xyz".

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

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

In this example, the call to AppendJustify() changes the content oftgt 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.

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

This call to AppendJustify() panics because the resulting length oftgt exceeds its maximum length.

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

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

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

The behaviour is the same for the build independent variant,TDes, replacing TBuf16with TBuf.

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

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

The behaviour is the same for the build independent variant,TDes, replacing _LIT16 with _LIT, and TBuf16with TBuf.

_LIT16(Kabc,"abc");
TBuf16<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

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

The behaviour is the same for the build independent variant,TDes, replacing _LIT16 with _LIT, and TBuf16with TBuf.

_LIT16(Kabc,"abc");
TBuf16<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"