<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-3D73DD8F-8D23-5D47-A4F7-3673C993EF8F" xml:lang="en"><title>Using

TDes8 Class</title><shortdesc>Use TDes8 for Interfaces which take binary data or narrow text

regardless of the build variant.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-8A5FCFAB-9D4A-540B-8958-0B5F43430F51"><title>Using in a

function interface</title> <p>An interface which needs to access and modify

binary data or explicit narrow text, regardless of the build variant, uses

a <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes8</apiname></xref> as the argument type. All 8 bit

concrete descriptors are derived from <codeph>TDes8</codeph> which means that

the interface can accept any 8 bit descriptor.</p> <p>The following code fragment

shows the most common function prototype pattern.</p> <codeblock id="GUID-937968D8-75F4-57ED-827E-14204E558F6D" xml:space="preserve">void ClassX::foo(TDes8&amp; anArg);</codeblock> <p>The use of <codeph>TDes8</codeph> means that data can be accessed and

modified through the descriptor.</p> <p>In practice, nearly all code uses

the build independent variant, <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes</apiname></xref>, unless

an explicit 8 bit or 16 bit build variant is required.</p> </section>

<section id="GUID-3D6C304C-E139-5090-BB8C-D05C234C954B"><title>Accessing individual

data items</title> <p>The code fragment illustrates the use of <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>operator[]()</apiname></xref>.</p> <p>The

behaviour is the same for the build independent variant, <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT</apiname></xref>.</p> <codeblock id="GUID-42F88AC7-8A5D-5B00-A146-22B27651328D" xml:space="preserve">_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");</codeblock> </section>

<section id="GUID-7C724770-09D1-5216-8FF1-BD7D6158F9EF"><title>Copying data</title> <p>The

code fragment shows the <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>Copy()</apiname></xref> function.</p> <p>The

behaviour is the same for the build independent variant, <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT</apiname></xref> and <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-46E1E65D-7F2C-5CCB-9DC3-788B03782521" xml:space="preserve">_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 !!

...

</codeblock> </section>

<section id="GUID-A1F3A661-54AD-5392-8633-0F8745EE1953"><title>Copying data

with repetition</title> <p>The code fragment shows the <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>Repeat()</apiname></xref> function.</p> <p>The

behaviour is the same for the build independent variant, <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT</apiname></xref> and <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-82594D00-50EA-54D8-AC4F-05A9D3DE6F7D" xml:space="preserve">_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"</codeblock> </section>

<section id="GUID-EED99668-9259-5802-A603-C17DF1F8DFA4"><title>Copying data

and justifying</title> <p>The code fragments show the<xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>Justify()</apiname></xref> function.</p> <p>The

behaviour is the same for the build independent variant, <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT</apiname></xref> and <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-8F124889-1DB8-581A-BD7B-533F9429D1DD" xml:space="preserve">_LIT8(Kabc,"abc");

TBuf8<16> tgt(Kabc);

...

tgt.Justify(_L("xyz"),8,ECenter,'@');</codeblock> <p>The descriptor <codeph>tgt</codeph> has

a maximum length of 16 and initially holds the string "<codeph>abc</codeph>".

After the call to <codeph>Justify()</codeph>, the content of <codeph>tgt</codeph> changes

to <codeph>"@@xyz@@@</codeph>".</p> <p>The content of the source descriptor

is taken to form a field of length 8 which replaces the original content of

the descriptor <codeph>tgt</codeph>. The characters "<codeph>xyz</codeph>"

are centred within the new field and padded on both sides with the fill character <codeph>'@'.</codeph></p> <p>Setting

the alignment to <codeph>ELeft</codeph> would change the content of <codeph>tgt</codeph> to

"<codeph>xyz@@@@@</codeph>" while setting the alignment to <codeph>ERight</codeph> would

change the content of <codeph>tgt</codeph> to "<codeph>@@@@@xyz</codeph>"</p> <p>In

all three cases, the length of the descriptor <codeph>tgt</codeph> changes

from 3 to 8.</p> <codeblock id="GUID-B4FC6164-2F2A-528E-B803-36B58D13F969" xml:space="preserve">_LIT8(Kabc,"abc");

_LIT8(Kxyz,"xyz");

TBuf8<8> tgt(Kabc);

...

tgt.Justify(Kxyz,9,ECenter,'@');</codeblock> <p>This call to <codeph>Justify()</codeph> panics

because the resulting length of data in <codeph>tgt</codeph> exceeds the maximum

length of <codeph>tgt</codeph>.</p> <codeblock id="GUID-2F3201CD-B184-5338-9715-BD6166AA6F9A" xml:space="preserve">_LIT8(Kabc,"abc");

_LIT8(KRtoZ,"rstuvwxyz");

TBuf8<16> tgt(Kabc);

...

tgt.Justify(KRtoZ,8,ECenter,'@');</codeblock> <p>In this call to <codeph>Justify()</codeph>,

the content of <codeph>tgt</codeph> changes to "<codeph>rstuvwxy</codeph>".

Only eight of the nine characters in the source literal <codeph>KRtoZ</codeph> are

copied.</p> </section>

<section id="GUID-B33F6D5B-05BB-5DCA-99B3-52C0A68D3128"><title>Copying conversion

from signed integer to decimal character</title> <p>The following code fragment

illustrates the use of <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>Num()</apiname></xref>.</p> <p>The

behaviour is the same for the build independent variant, <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-329B25B1-DAAB-5CDC-99CF-9CDDB75D8E9F" xml:space="preserve">TBuf8&lt;16&gt; tgt;

...

TInt numpos(176);

TInt numneg(-176);

..                      // generates the following strings:

tgt.Num(numpos);        // "176"

tgt.Num(numneg);        // "-176"</codeblock> </section>

<section id="GUID-2F66C889-8980-5AE3-BB9C-44C3939D7FD5"><title>Copying conversion

from unsigned integer to specified number system</title> <p>The following

code fragment illustrates the use of <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>Num()</apiname></xref> and <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>NumUC()</apiname></xref>.</p> <p>The behaviour is the same for the

build independent variant,<xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes</apiname></xref>, replacing <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf8</apiname></xref> with<xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-07EF83DC-361B-5B24-9A64-9021F5350CC9" xml:space="preserve">TBuf8&lt;16&gt; 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"  &lt;--EDecimal taken as default</codeblock> </section>

<section id="GUID-3CECD3B4-D14D-5983-9FD5-576D0950389B"><title>Formatting

text</title> <p>The following code fragments illustrate the various possibilities

of <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>Format()</apiname></xref>.</p> <p>The behaviour is the

same for the build independent variant, <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT</apiname></xref> and <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-0F649A7F-7192-5144-AF0C-B4FAA7FE9364" xml:space="preserve">TBuf8&lt;256&gt; 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]

</codeblock> </section>

<section id="GUID-DB6927AD-8B34-50CA-AECE-7A679E78854E"><title>Inserting data</title> <p>The

code fragment shows the <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>Insert()</apiname></xref> function.</p> <p>The

behaviour is the same for the build independent variant, <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT</apiname></xref> and <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-FE56DF6A-84AA-5A9F-93B6-EEFFA75B76CD" xml:space="preserve">_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);           // ----&gt; Panic !!</codeblock> </section>

<section id="GUID-3E97AA91-4E41-5D30-8D21-61A54A1DEDF5"><title>Replacing data</title> <p>The

following code fragment illustrates the use of <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>Replace()</apiname></xref>.</p> <p>The

behaviour is the same for the build independent variant, <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT</apiname></xref> and <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-D77F510D-F6C9-5AB8-B749-5D48E6D754A3" xml:space="preserve">_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"</codeblock> </section>

<section id="GUID-9CB5C056-52ED-5307-BA3A-65C3EA99B910"><title>Swapping data</title> <p>This

code fragment shows the <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>Swap()</apiname></xref> function.</p> <p>The

behaviour is the same for the build independent variant, <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT</apiname></xref> and <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-C99E6295-EFAC-5B7A-8C01-81D776C64A60" xml:space="preserve">_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 !!</codeblock> </section>

<section id="GUID-BD7F7862-5C75-52EF-9EF6-5DAC40E7541F"><title>Deleting data</title> <p>The

following code fragment illustrates the use of <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>Delete()</apiname></xref>.</p> <p>The

behaviour is the same for the build independent variant, <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT</apiname></xref> and <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-F086BB7B-A027-5B3E-B38A-17903D0D813C" xml:space="preserve">_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);            // ----&gt; Panics !!</codeblock> </section>

<section id="GUID-31B39F0B-09A0-5638-95DB-2B448D5572D4"><title>Deleting leading

spaces</title> <p>The following code fragment illustrates the use of <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TrimLeft()</apiname></xref>.</p> <p>The behaviour is the same for

the build independent variant, <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes</apiname></xref>, replacing <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT</apiname></xref> and <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-73F86C72-1009-5671-9AB1-1B96338C842D" xml:space="preserve">_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</codeblock> </section>

<section id="GUID-F7BAEAAE-C9DF-51CF-A0C9-5134D2DA67D5"><title>Deleting trailing

spaces</title> <p>The following code fragment illustrates the use of <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TrimRight()</apiname></xref>.</p> <p>The behaviour is the same for

the build independent variant, <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes</apiname></xref>, replacing <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT</apiname></xref> and <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-EF8C715B-8B19-512B-9C97-9BB3F626A2E6" xml:space="preserve">_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</codeblock> </section>

<section id="GUID-51B37E69-860A-55E0-BD25-C618128BB91C"><title>Deleting leading

and trailing spaces</title> <p>The following code fragment illustrates the

use of <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>Trim()</apiname></xref>.</p> <p>The behaviour is the

same for the build independent variant, <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT</apiname></xref> and <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-D1483F81-72DA-5B7D-8643-148789B14943" xml:space="preserve">_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</codeblock> </section>

<section id="GUID-CD96A766-8420-5E4C-AFA5-42F1A282C510"><title>Deleting leading,

trailing and internal spaces</title> <p>The following code fragment illustrates

the use of <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TrimAll()</apiname></xref>.</p> <p>The behaviour

is the same for the build independent variant, <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT</apiname></xref> and <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-91501E4D-C9D1-55F0-A9E0-82B547C0BFEB" xml:space="preserve">_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</codeblock> </section>

<section id="GUID-6565F27E-E838-55C8-AF8C-FEA23DBDD83B"><title>Append and

justify</title> <p>The following code fragments illustrate the use of <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>AppendJustify()</apiname></xref>.</p> <p>The behaviour is the same

for the build independent variant, <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT</apiname></xref> and <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-819F6F50-FB02-56F0-AC60-7A109498DD74" xml:space="preserve">_LIT8(Kabc,"abc");

_LIT8(Kxyz, "xyz");

...

TBuf8<16> tgt(Kabc);

tgt.AppendJustify(Kxyz,8,ECenter,'@');</codeblock> <p>The descriptor <codeph>tgt</codeph> has

a maximum length of 16 and initially holds the string "<codeph>abc</codeph>".

After the call to <codeph>AppendJustify()</codeph>, the content of <codeph>tgt</codeph> changes

to "<codeph>abc@@xyz@@@</codeph>".</p> <p>The content of the source descriptor <codeph>Kxyz</codeph> is

taken to form a field of length 8 which is appended to the content of the

descriptor <codeph>tgt</codeph>. The characters "<codeph>xyz</codeph>" are

centred within the new field and padded on both sides with the fill character <codeph>'@'.</codeph></p> <p>Setting

the alignment to <codeph>ELeft</codeph> would change the content of <codeph>tgt</codeph> to

"<codeph>abcxyz@@@@@</codeph>" while setting the alignment to <codeph>ERight</codeph> would

change the content of <codeph>tgt</codeph> to "<codeph>abc@@@@@xyz</codeph>".</p> <p>In

all three cases, the length of the descriptor <codeph>tgt</codeph> changes

from 3 to 11.</p> <codeblock id="GUID-2B2D253F-F4D2-5FE4-90CE-3B352246ECB2" xml:space="preserve">_LIT8(KAtoK,"abcdefghik");

_LIT8(K0to6,"0123456");

...

TBuf8<16> tgt(KAtoK);

tgt.AppendJustify(K0to6,7,ECenter,'@');</codeblock> <p>This call to <codeph>AppendJustify()</codeph> panics

because the resulting length of <codeph>tgt</codeph> exceeds its maximum length.</p> </section>

<section id="GUID-88473872-CF3A-5D4E-A6F5-24B2F3AE6FF1"><title>Append and

justify with explicit length</title> <p>The following code fragments illustrate

the use of the overloaded version of <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>AppendJustify()</apiname></xref> which

specifies an explicit length.</p> <p>The behaviour is the same for the build

independent variant,<xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TDes</apiname></xref>, replacing <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>_LIT</apiname></xref> and <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf8</apiname></xref> with <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-60769FA9-213E-5332-8E47-AA75FB94826C" xml:space="preserve">_LIT8(Kabc,"abc");

_LIT8(Kxyz0to9,"xyz0123456789");

...

TBuf8<16> tgt(Kabc);

tgt.AppendJustify(Kxyz0to9,3,8,ECenter,'@');</codeblock> <p>The descriptor <codeph>tgt</codeph> has

a maximum length of 16 and initially holds the string "<codeph>abc</codeph>".

After the call to <codeph>AppendJustify()</codeph>, the content of <codeph>tgt</codeph> changes

to "<codeph>abc@@xyz@@@</codeph>".</p> <p>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 <codeph>tgt</codeph>.

The three characters "<codeph>xyz</codeph>" are centred within the new field

and padded on both sides with the fill character <codeph>'@'.</codeph></p> <p>Setting

the alignment to <codeph>ELeft</codeph> would change the content of <codeph>tgt</codeph> to

"<codeph>abcxyz@@@@@</codeph>" while setting the alignment to <codeph>ERight</codeph> would

change the content of <codeph>tgt</codeph> to "<codeph>abc@@@@@xyz</codeph>".</p> <p>In

all three cases, the length of the descriptor <codeph>tgt</codeph> changes

from 3 to 11.</p> <codeblock id="GUID-52D44BB4-6FBE-5693-82F0-FEBB1E416B5D" xml:space="preserve">_LIT8(Kabc,"abc");

_LIT8(K0to9,"0123456789");

...

TBuf8<16> tgt(Kabc);

tgt.AppendJustify(K0to9,9,8,ECenter,'@');</codeblock> <p>In this example,