Using -TDes16 class

Using in a -function 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.

Accessing individual -data items

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

Copying data

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

Copying data -with repetition

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"

Copying data -and justifying

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.

Copying conversion -from signed integer to decimal character

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"

Copying conversion -from unsigned integer to specified number system

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

Formatting -text

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

Inserting data

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

Replacing data

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"

Swapping data

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

Deleting data

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

Deleting leading -spaces

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

Deleting trailing -spaces

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

Deleting leading -and trailing spaces

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

Deleting leading, -trailing and internal spaces

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

Append and -justify

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.

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 _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.

Append data -operator

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

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

Append conversion -from unsigned integer to specified number system

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

Append fixed -width conversion

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"

+ + + + + +Using +TDes16 classUse TDes16 for Interfaces which take wide (Unicode) text regardless +of the build variant. +

Using in a +function 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.

Accessing individual +data items

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

Copying data

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

Copying data +with repetition

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"

Copying data +and justifying

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.

Copying conversion +from signed integer to decimal character

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"

Copying conversion +from unsigned integer to specified number system

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

Formatting +text

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] + +

Inserting data

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

Replacing data

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"

Swapping data

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

Deleting data

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

Deleting leading +spaces

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

Deleting trailing +spaces

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

Deleting leading +and trailing spaces

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

Deleting leading, +trailing and internal spaces

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

Append and +justify

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.

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 _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.

Append data +operator

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

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

Append conversion +from unsigned integer to specified number system

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

Append fixed +width conversion

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"

\ No newline at end of file