Use TDes16 for Interfaces which take wide (Unicode) text regardless of the build variant.
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.
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 the Justify() function.
The
behaviour is the same for the build independent variant, TDes,
replacing _LIT16 with _LIT,
and TBuf16 withTBuf.
_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 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.
_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 in tgt 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 literalKRtoZ are copied.
The following code fragment
illustrates the use ofNum().
The
behaviour is the same for the build independent variant, TDes,
replacing TBuf16 withTBuf.
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 ofNum() and NumUC().
The behaviour is the same for the
build independent variant, TDes, replacing TBuf16 withTBuf.
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
ofFormat().
The behaviour is the
same for the build independent variant, TDes,
replacing _LIT16 with _LIT,
and TBuf16 withTBuf.
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]"); // pad char="0", field width=4
tgt.Format(KFormat2,65); //generates:
... //[0041]
...
_LIT16(KFormat3,"[%4x]"); // pad char=default, field width=4
tgt.Format(KFormat3,65); //generates:
... //[ 41]
... // Note use of blanks as default pad chars.
...
_LIT16(KFormat4,"[%*x]"); // fixed field width, taken from the arguments list
tgt.Format(KFormat4,4,65); //generates:
... //[ 41]
...
...
_LIT16(KFormat5,"[%+$4d.00 %S]"); // pad char="$", field width=4, right aligned
_LIT16(KOver,"over");
tgt.Format(KFormat5,65,&KOver); //generates:
... //[$$65.00 over]
...
_LIT16(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
...
_LIT16(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
...
_LIT16(KFormat8,"[%+0*S]"); // right aligned, pad char="0", fixed field width
_LIT16(KFred,"fred");
tgt.Format(KFormat8,10,&KFred); //generates:
... //[000000fred]
... // Note: 10 characters generated
...
_LIT16(KFormat9,"[%=*6x]"); // centre aligned, pad char taken from arguments list, field width=6
tgt.Format(KFormat9,'*',65); //generates:
... //[**41**]
...
_LIT16(KFormat10,"[%+**d]"); // right aligned, pad char and field width taken from arguments list
tgt.Format(KFormat10,'.',10,(-65)); //generates:
... //[.......-65]
...
_LIT16(KFormat11,"[%-A4p]"); // left aligned, field width=4, pad char="A"
tgt.Format(KFormat11,65); //generates
... //[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]");
tgt.Format(KFormat16,3.4555); //generates:
... //[3.46E+00]
_LIT16(KFormat17,"[%6.2f]");
tgt.Format(KFormat17,3.4555); //generates:
... //[ 3.46]
_LIT16(KFormat18,"[%6.2g]");
tgt.Format(KFormat18,3.4555); //generates:
//[3.4555]
...
// Variable argument positions
_LIT16(KFormat19,"[%d %d]"); // implicit ordering
tgt.Format(KFormat19,9,5); // generates:
... // [9 5]
...
_LIT16(KFormat20,"[%$2$d %$1$d]"); // explicit ordering
tgt.Format(KFormat20,9,5); // generates:
... // [5 9]
...
_LIT16(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)
_LIT16(KFormat22,"[%0*d %d %d]"); // implicit ordering
tgt.Format(KFormat22,3,9,5,12); // generates:
... // [009 5 12]
...
_LIT16(KFormat23,"[%$2$d %$1$0*d %d]"); // mixed explicit and implicit ordering
tgt.Format(KFormat23,3,9,5,12); // generates:
... // [5 009 12]
...
_LIT16(KFormat24,"[%$3$d %$1$0*d %$2$d]"); // explicit ordering
tgt.Format(KFormat24,3,9,5,12); // generates:
... // [12 009 5]
The
code fragment shows the Insert() function.
The
behaviour is the same for the build independent variant, TDes,
replacing _LIT16 with _LIT,
and TBuf16 withTBuf.
_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 ofReplace().
The
behaviour is the same for the build independent variant, TDes,
replacing _LIT16 with _LIT,
and TBuf16 withTBuf.
_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 TBuf16 withTBuf.
_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 ofDelete().
The
behaviour is the same for the build independent variant, TDes,
replacing _LIT16 with _LIT,
and TBuf16 withTBuf.
_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 ofTrimLeft().
The behaviour is the same for
the build independent variant, TDes, replacing _LIT16 with _LIT,
and TBuf16 withTBuf.
_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 ofTrimRight().
The behaviour is the same for
the build independent variant, TDes, replacing _LIT16 with _LIT,
and TBuf16 withTBuf.
_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 ofTrim().
The behaviour is the
same for the build independent variant, TDes,
replacing _LIT16 with _LIT,
and TBuf16 withTBuf.
_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 ofTrimAll().
The behaviour
is the same for the build independent variant, TDes,
replacing _LIT16 with _LIT,
and TBuf16 withTBuf.
_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 ofAppendJustify().
The behaviour is the same
for the build independent variant, TDes,
replacing _LIT16 with _LIT,
and TBuf16 withTBuf.
_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 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.
_LIT16(KAtoK,"abcdefghik"); _LIT16(K0to6,"0123456"); ... TBuf16<16> tgt(KAtoK); tgt.AppendJustify(K0to6,7,ECenter,'@');
This call to AppendJustify() panics
because the resulting length of tgt 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 TBuf16 withTBuf.
_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 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.
_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 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.
_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 of tgt exceeds its maximum length.
The following code fragment illustrates the use ofoperator+=().
_LIT16(Kabc,"abc");
TBuf16<16> tgt(Kabc);
...
tgt+=(_L("0123456789")); // generates "abc0123456789"
tgt+=(_L("0123456789qwerty")); // Panics !! The following code fragment
illustrates the use ofAppendNum().
The
behaviour is the same for the build independent variant, TDes,
replacing TBuf16 withTBuf.
_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 ofAppendNum() and AppendNumUC().
The behaviour is the same
for the build independent variant, TDes,
replacing _LIT16 with _LIT,
and TBuf16 withTBuf.
_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
ofAppendNumFixedWidth() andAppendNumFixedWidthUC().
The
behaviour is the same for the build independent variant, TDes,
replacing _LIT16 with _LIT,
and TBuf16 withTBuf.
_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"