TDes8
Class
Interfaces which take binary data or narrow text, use descriptors in the specification of that 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.
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");
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 !!
...
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"
The code fragments show the
Justify()
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.
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"
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
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]
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 !!
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"
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 !!
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 !!
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
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
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
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
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.
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.
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 !!
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"
The following code fragment illustrates the use
of AppendNum()
and
AppendNumUC()
.
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
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"