Week 28 contribution of SDK documentation content. See release notes for details. Fixes bugs Bug 1897 and Bug 1522.
<?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& 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<16> 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<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</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<256> tgt;
...
_LIT16(KFormat1,"[%b %c %d %o %u %x]");
tgt.Format(KFormat1,65,65,65,65,65,65);//generates:
... //[1000001 A 65 101 65 41]
...
_LIT16(KFormat2,"[%04x]"); // pad char="0", field width=4
tgt.Format(KFormat2,65); //generates:
... //[0041]
...
_LIT16(KFormat3,"[%4x]"); // pad char=default, field width=4
tgt.Format(KFormat3,65); //generates:
... //[ 41]
... // Note use of blanks as default pad chars.
...
_LIT16(KFormat4,"[%*x]"); // fixed field width, taken from the arguments list
tgt.Format(KFormat4,4,65); //generates:
... //[ 41]
...
...
_LIT16(KFormat5,"[%+$4d.00 %S]"); // pad char="$", field width=4, right aligned
_LIT16(KOver,"over");
tgt.Format(KFormat5,65,&KOver); //generates:
... //[$$65.00 over]
...
_LIT16(KFormat6,"[%+4d.00 %S]"); // pad char=default, field width=4
tgt.Format(KFormat6,65,&KOver); //generates:
... //[ 65.00 over]
... // note no pad char specified, defaults
... // to blank
...
_LIT16(KFormat7,"[% 4d.00 %S]"); // pad char=" ", field width=4, alignment=default
tgt.Format(KFormat7,65,&KOver); //generates:
... //[ 65.00 over]
... // note default right hand alignment and
... // blank pad char
...
_LIT16(KFormat8,"[%+0*S]"); // right aligned, pad char="0", fixed field width
_LIT16(KFred,"fred");
tgt.Format(KFormat8,10,&KFred); //generates:
... //[000000fred]
... // Note: 10 characters generated
...
_LIT16(KFormat9,"[%=*6x]"); // centre aligned, pad char taken from arguments list, field width=6
tgt.Format(KFormat9,'*',65); //generates:
... //[**41**]
...
_LIT16(KFormat10,"[%+**d]"); // right aligned, pad char and field width taken from arguments list
tgt.Format(KFormat10,'.',10,(-65)); //generates:
... //[.......-65]
...
_LIT16(KFormat11,"[%-A4p]"); // left aligned, field width=4, pad char="A"
tgt.Format(KFormat11,65); //generates
... //[AAAA]
... // and makes no use of the argument list
...
_LIT16(KFormat12,"[%m]"); //generates:
tgt.Format(KFormat12,4660); // the char '['
... // followed by a byte with 0x12
... // followed by a byte with 0x34
... // followed by the char ']'
_LIT16(KFormat13,"[%M]")
tgt.Format(KFormat13,4660); //generates:
... // the char '['
... // followed by a byte with 0x00
... // followed by a byte with 0x00
... // followed by a byte with 0x12
... // followed by a byte with 0x34
... // followed by the char ']'
...
_LIT16(KFormat14,"[%w]"); //generates:
tgt.Format(KFormat14,4660); // the char '['
... // followed by a byte with 0x34
... // followed by a byte with 0x12
... // followed by the char ']'
..
_LIT16(KFormat15,"[%w]"); //generates:
tgt.Format(KFormat15,4660); // the char '['
... // followed by a byte with 0x34
... // followed by a byte with 0x12
... // followed by a byte with 0x00
... // followed by a byte with 0x00
... // followed by the char ']'
...
_LIT16(KFormat16,"[%6.2e]");
tgt.Format(KFormat16,3.4555); //generates:
... //[3.46E+00]
_LIT16(KFormat17,"[%6.2f]");
tgt.Format(KFormat17,3.4555); //generates:
... //[ 3.46]
_LIT16(KFormat18,"[%6.2g]");
tgt.Format(KFormat18,3.4555); //generates:
//[3.4555]
...
// Variable argument positions
_LIT16(KFormat19,"[%d %d]"); // implicit ordering
tgt.Format(KFormat19,9,5); // generates:
... // [9 5]
...
_LIT16(KFormat20,"[%$2$d %$1$d]"); // explicit ordering
tgt.Format(KFormat20,9,5); // generates:
... // [5 9]
...
_LIT16(KFormat21,"[%$1$d %$2$d]"); // explicit ordering (same as the implicit order)
tgt.Format(KFormat21,9,5); // generates:
... // [9 5]
// Using argument blocks (a many-to-one mapping between arguments and conversion specifiers)
_LIT16(KFormat22,"[%0*d %d %d]"); // implicit ordering
tgt.Format(KFormat22,3,9,5,12); // generates:
... // [009 5 12]
...
_LIT16(KFormat23,"[%$2$d %$1$0*d %d]"); // mixed explicit and implicit ordering
tgt.Format(KFormat23,3,9,5,12); // generates:
... // [5 009 12]
...
_LIT16(KFormat24,"[%$3$d %$1$0*d %$2$d]"); // explicit ordering
tgt.Format(KFormat24,3,9,5,12); // generates:
... // [12 009 5]
</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); // ----> 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); // ----> 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
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-7ADD1986-D57E-55B3-8C78-EDF7E8C97F3A" xml:space="preserve">_LIT16(Kabc,"abc");
_LIT16(K0to9,"0123456789");
...
TBuf16<16> tgt(Kabc);
tgt.AppendJustify(K0to9,9,8,ECenter,'@');</codeblock> <p>In this example,
the call to <codeph>AppendJustify()</codeph> changes the content of <codeph>tgt</codeph> to
"<codeph>abc01234567</codeph>". 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.</p> <codeblock id="GUID-DC7F6C77-14D0-5922-AD4A-C5CCE2B99A81" xml:space="preserve">_LIT16(KAtoK,"abcdefghik");
_LIT16(K0to9,"0123456789");
...
TBuf16<16> tgt(KAtoK);
tgt.AppendJustify(K0to9,3,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-E844DB49-2BDA-56BD-92AB-5FB23D2274D2"><title>Append data
operator</title> <p>The following code fragment illustrates the use of<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>operator+=()</apiname></xref>.</p> <codeblock id="GUID-F8E72C51-2DAA-5AB9-ADB3-AA1830020116" xml:space="preserve">_LIT16(Kabc,"abc");
TBuf16<16> tgt(Kabc);
...
tgt+=(_L("0123456789")); // generates "abc0123456789"
tgt+=(_L("0123456789qwerty")); // Panics !!</codeblock> </section>
<section id="GUID-F056485E-28FF-5E20-82D7-884D486174E3"><title>Append 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>AppendNum()</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-14953E84-47E5-5BA5-8EB8-11E4A062A8A9" xml:space="preserve">_LIT16(Kabc,"abc");
TInt numpos(176);
TInt numneg(-176);
...
TBuf16<16> tgt(Kabc)); // generates the following strings:
tgt.AppendNum(numpos); // "abc176"
tgt.AppendNum(numneg); // "abc-176"</codeblock> </section>
<section id="GUID-0B59128B-2152-5CB3-8363-457CDB18768D"><title>Append 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>AppendNum()</apiname></xref> and <xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>AppendNumUC()</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-0DBF2078-5B45-5865-9B15-14ED2C29DC27" xml:space="preserve">_LIT16(Kabc,"abc");
TBuf16<16> tgt(Kabc); // generates the following strings:
...
TUint num(170);
...
tgt.AppendNum(num,EBinary); // "abc10101010"
tgt.AppendNum(num,EOctal); // "abc252"
tgt.AppendNum(num,EDecimal); // "abc170"
tgt.AppendNum(num,EHex); // "abcaa" <-hex value in lower case
tgt.AppendNumUC(num,EHex); // "abcAA" <-hex value in UPPER case
tgt.AppendNum(num); // "abc170" <-EDecimal taken as default</codeblock> </section>
<section id="GUID-7A61CC57-7AC3-5AFD-9E3F-1FFAD4D9EF3E"><title>Append fixed
width conversion</title> <p>The following code fragment illustrates the use
of<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>AppendNumFixedWidth()</apiname></xref> and<xref href="GUID-C04A9A0C-DBA7-37DA-B744-54FBF3D544CD.dita"><apiname>AppendNumFixedWidthUC()</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-344F9FBD-83BC-599C-A762-ED7CBD5ED060" xml:space="preserve">_LIT16(Kabc,"abc");
TBuf16<16> tgt(Kabc); // generates the following strings:
...
TUint num(170)
...
tgt.AppendNumFixedWidth(num,EBinary,8); // "abc10101010"
tgt.AppendNumFixedWidth(num,EOctal,8); // "abc00000252"
tgt.AppendNumFixedWidth(num,EDecimal,8); // "abc00000170"
tgt.AppendNumFixedWidth(num,EHex,8); // "abc000000aa"
tgt.AppendNumFixedWidthUC(num,EHex,8); // "abc000000AA"</codeblock> </section>
</conbody></concept>