Using TDes8 Class

Use TDes8 for Interfaces which take binary data or narrow text regardless of the build variant.

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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]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, [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]TDes, unless an explicit 8 bit or 16 bit build variant is required.

Accessing individual data items

The code fragment illustrates the use of [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]operator[]().

_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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]Copy() function.

The behaviour is the same for the build independent variant, [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]TDes, replacing [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]_LIT8 with [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]_LIT and [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]TBuf8 with [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]Repeat() function.

_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 the[[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]Justify() function.

_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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]Num().

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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]Num() and [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]NumUC().

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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]Format().

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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]Insert() function.

_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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]Replace().

_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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]Swap() function.

_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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]Delete().

_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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]TrimLeft().

_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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]TrimRight().

_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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]Trim().

_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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]TrimAll().

_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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]AppendJustify().

_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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]AppendJustify() which specifies an explicit length.

The behaviour is the same for the build independent variant,[[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]TDes, replacing [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]_LIT8 with [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]_LIT and [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]TBuf8 with [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]AppendNum().

_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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]AppendNum() and[[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]AppendNumUC().

_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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]AppendNumFixedWidth() and [[[ERROR: [NOKX000E] Unable to find definition for key reference 'TDes8']]]AppendNumFixedWidthUC().

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