<?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-0B6C97D3-0E2D-5BBE-B8AC-985902715160" xml:lang="en"><title>Using

TDes16 class</title><shortdesc>Use TDes16 for Interfaces which take wide (Unicode) text regardless

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

<section id="GUID-D4D5A59E-C9E5-5729-8730-5365C7922CFE"><title>Using in a

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

Unicode text, regardless of the build variant, uses a <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TDes16</apiname></xref> as

the argument type. All 16 bit concrete descriptors are derived from <codeph>TDes16</codeph> which

means that the interface can accept any 16 bit descriptor.</p> <p>The following

code fragment shows the most common function prototype pattern.</p> <codeblock id="GUID-70EBC544-5308-52AA-8777-0DFB5D73F7D0" xml:space="preserve">void ClassX::foo(TDes16&amp; anArg);</codeblock> <p>The

use of <codeph>TDes16</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-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TDes</apiname></xref>, unless an explicit

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

<section id="GUID-C1F88768-4489-5A99-8512-7BE80C80EB25"><title>Accessing individual

data items</title> <p>The code fragment illustrates the use of <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>operator[]()</apiname></xref>.</p> <p>The

behaviour is the same for the build independent variant, <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT16</apiname></xref> with <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT</apiname></xref>.</p> <codeblock id="GUID-CBB66254-2E53-5F18-A547-941CDE264B30" xml:space="preserve">_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 !!</codeblock> </section>

<section id="GUID-3E72CE9C-4C1A-5861-BCEE-B481809F5837"><title>Copying data</title> <p>The

code fragment shows the <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>Copy()</apiname></xref> function.</p> <p>The

behaviour is the same for the build independent variant, <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT16</apiname></xref> with <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT</apiname></xref>,

and <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf16</apiname></xref> with <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-31357819-E92C-5D81-936D-8A31291CCCFD" xml:space="preserve">_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 !!</codeblock> </section>

<section id="GUID-109A36A8-9FC0-59F0-96F5-A3BC86E07795"><title>Copying data

with repetition</title> <p>The code fragment shows the <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>Repeat()</apiname></xref> function.</p> <p>The

behaviour is the same for the build independent variant, <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT16</apiname></xref> with <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT</apiname></xref>,

and <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf16</apiname></xref> with <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-02ABA404-871E-555B-BBC7-B7A2C5796D0F" xml:space="preserve">_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"</codeblock> </section>

<section id="GUID-C7A4D40E-F4D3-5683-91DE-91FE2C5D63DE"><title>Copying data

and justifying</title> <p>The code fragments show the <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>Justify()</apiname></xref> function.</p> <p>The

behaviour is the same for the build independent variant, <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT16</apiname></xref> with <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT</apiname></xref>,

and <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf16</apiname></xref> with<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-E8EEC5B9-846F-5352-9072-E7F19D751BFB" xml:space="preserve">_LIT16(Kabc,"abc");

TBuf16<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 "abc". 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-084D5402-03A8-5A6C-ACBE-150594CC995F" xml:space="preserve">_LIT16(Kabc,"abc");

_LIT16(Kxyz,"xyz");

TBuf16<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-620AA4E5-F6E8-5A68-B7D1-3D1D4549A5F6" xml:space="preserve">_LIT16(Kabc,"abc");

_LIT16(KRtoZ,"rstuvwxyz");

TBuf16<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 "rstuvwxy". Only eight of the

nine characters in the source literal<codeph>KRtoZ</codeph> are copied.</p> </section>

<section id="GUID-73C9CA90-5D00-5CD3-853C-9C03AE44D052"><title>Copying conversion

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

illustrates the use of<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>Num()</apiname></xref>.</p> <p>The

behaviour is the same for the build independent variant, <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf16</apiname></xref> with<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-B57E9FE0-17F7-55EB-96DA-C1BEDA29A11C" xml:space="preserve">TBuf16&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-9C8DC02F-C399-51EB-A675-FFF021626D88"><title>Copying conversion

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

code fragment illustrates the use of<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>Num()</apiname></xref> and <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>NumUC()</apiname></xref>.</p> <p>The behaviour is the same for the

build independent variant, <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TDes</apiname></xref>, replacing <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf16</apiname></xref> with<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-EE8FAF1C-F74E-5CCB-B5D2-92298BE2B0A5" xml:space="preserve">TBuf16&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-E0D95020-9E74-5FE1-8A84-74FFE8C2CB1E"><title>Formatting

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

of<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>Format()</apiname></xref>.</p> <p>The behaviour is the

same for the build independent variant, <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT16</apiname></xref> with <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT</apiname></xref>,

and <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf16</apiname></xref> with<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-39F9392D-32CD-5CDF-B5B8-DBDDD708738F" xml:space="preserve">TBuf16&lt;256&gt; 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]

</codeblock> </section>

<section id="GUID-6500B0CB-54FF-5358-A27F-16F42C4111C8"><title>Inserting data</title> <p>The

code fragment shows the <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>Insert()</apiname></xref> function.</p> <p>The

behaviour is the same for the build independent variant, <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT16</apiname></xref> with <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT</apiname></xref>,

and <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf16</apiname></xref> with<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-BB71E3D6-2BE0-5687-A030-1C030D1D4D7A" xml:space="preserve">_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);           // ----&gt; Panic !!</codeblock> </section>

<section id="GUID-1A3976EB-6A46-5F6F-B190-ACEA13474EBD"><title>Replacing data</title> <p>The

following code fragment illustrates the use of<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>Replace()</apiname></xref>.</p> <p>The

behaviour is the same for the build independent variant, <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT16</apiname></xref> with <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT</apiname></xref>,

and <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf16</apiname></xref> with<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-13F5FDC8-07DA-5818-A2DF-7F58757C4558" xml:space="preserve">_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"</codeblock> </section>

<section id="GUID-1F92A7F4-2206-5B60-B020-AFAB4720DC54"><title>Swapping data</title> <p>This

code fragment shows the <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>Swap()</apiname></xref> function.</p> <p>The

behaviour is the same for the build independent variant, <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT16</apiname></xref> with <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT</apiname></xref>,

and <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf16</apiname></xref> with<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-79B2CD79-D203-5958-9738-4DD9EF91D659" xml:space="preserve">_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 !!</codeblock> </section>

<section id="GUID-883167BC-E97D-5826-AA1A-41D1C3F0BF18"><title>Deleting data</title> <p>The

following code fragment illustrates the use of<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>Delete()</apiname></xref>.</p> <p>The

behaviour is the same for the build independent variant, <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT16</apiname></xref> with <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT</apiname></xref>,

and <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf16</apiname></xref> with<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-0EB429E5-BAC6-502B-B73C-16EC701AA439" xml:space="preserve">_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);           // ----&gt; Panics !!</codeblock> </section>

<section id="GUID-19E04508-8752-50BC-9570-4DF826461F8B"><title>Deleting leading

spaces</title> <p>The following code fragment illustrates the use of<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TrimLeft()</apiname></xref>.</p> <p>The behaviour is the same for

the build independent variant, <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TDes</apiname></xref>, replacing <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT16</apiname></xref> with <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT</apiname></xref>,

and <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf16</apiname></xref> with<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-95FD982B-0398-5BA8-AA26-79EB6CEC0193" xml:space="preserve">_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</codeblock> </section>

<section id="GUID-2EB9B1C4-A39A-5696-B0F0-9CC6DFD8AE44"><title>Deleting trailing

spaces</title> <p>The following code fragment illustrates the use of<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TrimRight()</apiname></xref>.</p> <p>The behaviour is the same for

the build independent variant, <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TDes</apiname></xref>, replacing <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT16</apiname></xref> with <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT</apiname></xref>,

and <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf16</apiname></xref> with<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-EC730EBE-BD56-5E95-AAA3-B704CA19C189" xml:space="preserve">_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</codeblock> </section>

<section id="GUID-94016BAD-FED1-5BDB-875A-E9C03D1C400F"><title>Deleting leading

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

use of<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>Trim()</apiname></xref>.</p> <p>The behaviour is the

same for the build independent variant, <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT16</apiname></xref> with <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT</apiname></xref>,

and <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf16</apiname></xref> with<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-6446EB8B-AF08-53B4-8554-5DE6639BDD5C" xml:space="preserve">_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</codeblock> </section>

<section id="GUID-804382DD-9790-5E11-A6F4-112DA7C30C1E"><title>Deleting leading,

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

the use of<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TrimAll()</apiname></xref>.</p> <p>The behaviour

is the same for the build independent variant, <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT16</apiname></xref> with <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT</apiname></xref>,

and <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf16</apiname></xref> with<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-101C5202-1FCA-5720-AA6C-6006229BBAE7" xml:space="preserve">_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</codeblock> </section>

<section id="GUID-B84DE2E8-6E4B-509C-9A43-F1134736BA04"><title>Append and

justify</title> <p>The following code fragments illustrate the use of<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>AppendJustify()</apiname></xref>.</p> <p>The behaviour is the same

for the build independent variant, <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TDes</apiname></xref>,

replacing <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT16</apiname></xref> with <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT</apiname></xref>,

and <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf16</apiname></xref> with<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-88672250-8C80-5AA4-B26A-44E73FD2C90E" xml:space="preserve">_LIT16(Kabc,"abc");

_LIT16(Kxyz, "xyz");

...

TBuf16<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-F5C0525B-CAAD-5068-8C54-28A7EFBA02A3" xml:space="preserve">_LIT16(KAtoK,"abcdefghik");

_LIT16(K0to6,"0123456");

...

TBuf16<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-A6018CB3-8452-5A6E-876A-337D7496D2A3"><title>Append and

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

the use of the overloaded version of <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.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-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TDes</apiname></xref>, replacing <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT16</apiname></xref> with <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>_LIT</apiname></xref>,

and <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf16</apiname></xref> with<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>TBuf</apiname></xref>.</p> <codeblock id="GUID-D5496168-D727-574C-A2C3-C23ABCC3DA23" xml:space="preserve">_LIT16(Kabc,"abc");

_LIT16(Kxyz0to9,"xyz0123456789");

...

TBuf16<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 "<codeph>xyz0123456789</codeph>" 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