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-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& 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<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-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<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-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<256> tgt;
...
_LIT8(KFormat1,"[%b %c %d %o %u %x]");
tgt.Format(KFormat1,65,65,65,65,65,65);//generates:
... //[1000001 A 65 101 65 41]
...
_LIT8(KFormat2,"[%04x]"); // pad char="0", field width=4
tgt.Format(KFormat2,65); //generates:
... //[0041]
...
_LIT8(KFormat3,"[%4x]"); // pad char=default, field width=4
tgt.Format(KFormat3,65); //generates:
... //[ 41]
... // Note use of blanks as default pad chars.
...
_LIT8(KFormat4,"[%*x]"); // fixed field width, taken from the arguments list
tgt.Format(KFormat4,4,65); //generates:
... //[ 41]
...
...
_LIT8(KFormat5,"[%+$4d.00 %S]"); // pad char="$", field width=4, right aligned
_LIT8(KOver,"over");
tgt.Format(KFormat5,65,&KOver); //generates:
... //[$$65.00 over]
...
_LIT8(KFormat6,"[%+4d.00 %S]"); // pad char=default, field width=4
tgt.Format(KFormat6,65,&KOver); //generates:
... //[ 65.00 over]
... // note no pad char specified, defaults
... // to blank
...
_LIT8(KFormat7,"[% 4d.00 %S]"); // pad char=" ", field width=4, alignment=default
tgt.Format(KFormat7,65,&KOver); //generates:
... //[ 65.00 over]
... // note default right hand alignment and
... // blank pad char
...
_LIT8(KFormat8,"[%+0*S]"); // right aligned, pad char="0", fixed field width
_LIT8(KFred,"fred");
tgt.Format(KFormat8,10,&KFred); //generates:
... //[000000fred]
... // Note - 10 characters generated
...
_LIT8(KFormat9,"[%=*6x]"); // centre aligned, pad char taken from arguments list, field width=6
tgt.Format(KFormat9,'*',65); //generates:
... //[**41**]
...
_LIT8(KFormat10,"[%+**d]"); // right aligned, pad char and field width taken from arguments list
tgt.Format(KFormat10,'.',10,(-65)); //generates:
... //[.......-65]
...
_LIT8(KFormat11,"[%-A4p]"); // left aligned, field width=4, pad char="A"
tgt.Format(KFormat11,65); //generates:
... //[AAAA]
... // and makes no use of the argument list
...
_LIT8(KFormat12,"[%m]"); //generates:
tgt.Format(KFormat12,4660); // the char '['
... // followed by a byte with 0x12
... // followed by a byte with 0x34
... // followed by the char ']'
_LIT8(KFormat13,"[%M]")
tgt.Format(KFormat13,4660); //generates:
... // the char '['
... // followed by a byte with 0x00
... // followed by a byte with 0x00
... // followed by a byte with 0x12
... // followed by a byte with 0x34
... // followed by the char ']'
...
_LIT8(KFormat14,"[%w]"); //generates:
tgt.Format(KFormat14,4660); // the char '['
... // followed by a byte with 0x34
... // followed by a byte with 0x12
... // followed by the char ']'
..
_LIT8(KFormat15,"[%w]"); //generates:
tgt.Format(KFormat15,4660); // the char '['
... // followed by a byte with 0x34
... // followed by a byte with 0x12
... // followed by a byte with 0x00
... // followed by a byte with 0x00
... // followed by the char ']'
...
_LIT8(KFormat16,"[%6.2e]");
tgt.Format(KFormat16,3.4555); //generates:
... //[3.46E+00]
_LIT8(KFormat17,"[%6.2f]");
tgt.Format(KFormat17,3.4555); //generates:
... //[ 3.46]
_LIT8(KFormat18,"[%6.2g]");
tgt.Format(KFormat18,3.4555); //generates:
... //[3.4555]
...
// Variable argument positions
_LIT8(KFormat19,"[%d %d]"); // implicit ordering
tgt.Format(KFormat19,9,5); // generates:
... // [9 5]
...
_LIT8(KFormat20,"[%$2$d %$1$d]"); // explicit ordering
tgt.Format(KFormat20,9,5); // generates:
... // [5 9]
...
_LIT8(KFormat21,"[%$1$d %$2$d]"); // explicit ordering (same as the implicit order)
tgt.Format(KFormat21,9,5); // generates:
... // [9 5]
// Using argument blocks (a many-to-one mapping between arguments and conversion specifiers)
_LIT8(KFormat22,"[%0*d %d %d]"); // implicit ordering
tgt.Format(KFormat22,3,9,5,12); // generates:
... // [009 5 12]
...
_LIT8(KFormat23,"[%$2$d %$1$0*d %d]"); // mixed explicit and implicit ordering
tgt.Format(KFormat23,3,9,5,12); // generates:
... // [5 009 12]
...
_LIT8(KFormat24,"[%$3$d %$1$0*d %$2$d]"); // explicit ordering
tgt.Format(KFormat24,3,9,5,12); // generates:
... // [12 009 5]
</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); // ----> 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); // ----> 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,
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-2AC4FE0B-0E59-5CBA-9CEB-52BE8852645D" xml:space="preserve">_LIT8(KAtoK,"abcdefghik");
_LIT8(K0to9,"0123456789");
...
TBuf8<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-E25AD363-D025-549A-A768-E669054B276A"><title>Append data
operator</title> <p>The following code fragment illustrates the use of <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>operator+=()</apiname></xref>.</p> <codeblock id="GUID-F445ADA1-82E5-5612-8342-32F67C21B0F5" xml:space="preserve">_LIT8(Kabc,"abc");
TBuf8<16> tgt(Kabc);
...
tgt+=(_L("0123456789")); // generates "abc0123456789"
tgt+=(_L("0123456789qwerty")); // Panics !!</codeblock> </section>
<section id="GUID-D8FE4EAA-40B1-5B60-8B3D-0DD4FF0EC01A"><title>Append 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>AppendNum()</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-C9DA1F31-97FD-5B14-90A2-4A129D95C1A0" xml:space="preserve">_LIT8(Kabc,"abc");
TInt numpos(176);
TInt numneg(-176);
...
TBuf8<16> tgt(Kabc)); // generates the following strings:
tgt.AppendNum(numpos); // "abc176"
tgt.AppendNum(numneg); // "abc-176"</codeblock> </section>
<section id="GUID-73D28A65-48E9-5E77-8BEF-CCAE312AC7D3"><title>Append 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>AppendNum()</apiname></xref> and<xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>AppendNumUC()</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-1FABB0D8-205F-53C6-82A5-2CE70373E6CC" xml:space="preserve">_LIT8(Kabc,"abc");
TBuf8<16> tgt(Kabc); // generates the following strings:
...
TUint num(170);
...
tgt.AppendNum(num,EBinary); // "abc10101010"
tgt.AppendNum(num,EOctal); // "abc252"
tgt.AppendNum(num,EDecimal);// "abc170"
tgt.AppendNum(num,EHex); // "abcaa" <-hex value in lower case
tgt.AppendNumUC(num,EHex); // "abcAA" <-hex value in UPPER case
tgt.AppendNum(num); // "abc170" <-EDecimal taken as default</codeblock> </section>
<section id="GUID-7CF714F2-9691-59E2-8178-25D7EC290117"><title>Append fixed
width conversion</title> <p>The following code fragment illustrates the use
of <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>AppendNumFixedWidth()</apiname></xref> and <xref href="GUID-445B19E5-E2EE-32E2-8D6C-C7D6A9B3C507.dita"><apiname>AppendNumFixedWidthUC()</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-B5997983-347D-5F85-B7D7-952A9BD170CE" xml:space="preserve">_LIT8(Kabc,"abc");
TBuf8<16> tgt(Kabc); // generates the following strings:
...
TUint num(170)
...
tgt.AppendNumFixedWidth(num,EBinary,8); // "abc10101010"
tgt.AppendNumFixedWidth(num,EOctal,8); // "abc00000252"
tgt.AppendNumFixedWidth(num,EDecimal,8); // "abc00000170"
tgt.AppendNumFixedWidth(num,EHex,8); // "abc000000aa"
tgt.AppendNumFixedWidthUC(num,EHex,8); // "abc000000AA"</codeblock> </section>
</conbody></concept>