<?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-F46D5A5B-EC44-53B0-9A11-886735B28610" xml:lang="en"><title>How to
use the modifiable pointer descriptor — TPtr</title><shortdesc>Modifiable pointer descriptors are useful for referencing strings
or data which can be accessed and changed.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<ul>
<li id="GUID-80F50BD5-A919-5EB3-B28E-4BDF7A2A0121"><p>For text data, it is
usual to construct a <codeph>TPtr</codeph> type and allow the appropriate
variant, either a <codeph>TPtr</codeph> or a <codeph>TPtrC</codeph> to be
selected at build time.</p> </li>
<li id="GUID-965CB6DC-DE3E-5744-A6D8-10C9A0567011"><p>For binary data, an
explicit <codeph>TPtr8</codeph> is used.</p> </li>
<li id="GUID-40B8DB60-33DB-56D3-BDE7-263B1B48840E"><p>It is rare to use an
explicit <codeph>TPtr16</codeph>.</p> </li>
</ul>
<section id="GUID-AEBBFA2C-D87D-48F8-ADBF-0A042F371EC1"><title>Constructing a TPtr</title> <p>A modifiable pointer descriptor
can be constructed in a number of ways:</p> <ul>
<li id="GUID-C3767C93-A5BA-5B09-A90D-FAD74E9CDC3F"><p>another modifiable pointer
descriptor.</p> </li>
<li id="GUID-9704F005-0931-5DA0-B4C7-7F263270300C"><p>from a non-modifiable
buffer descriptor using the <codeph>Des()</codeph> function</p> </li>
<li id="GUID-2F09FD0B-7FE7-5D4E-B353-233B2609F9FC"><p>from an explicit pointer
into memory and specifying a maximum length.</p> </li>
<li id="GUID-F9C4E446-B390-56AD-8771-A0C393ADA246"><p>from an explicit pointer
into memory and specifying the length of the data and a maximum length.</p> </li>
</ul> <p>The following code fragment constructs a <codeph>TPtr</codeph> to
represent the data already represented by another <codeph>TPtr</codeph>:</p> <codeblock id="GUID-B9296BAB-8B81-52C4-9730-2290C357656A" xml:space="preserve">TPtr ptr1;
...
TPtr ptr2(ptr1);
...</codeblock> <p>The following code fragment constructs a <codeph>TPtr</codeph> for
a non-modifiable buffer descriptor, a <codeph>TBufC&lt;TInt&gt;</codeph>, using
the <codeph>Des()</codeph> function. Data that would normally be unmodifiable
through the <codeph>TBufC&lt;TInt&gt;</codeph> can be changed through the <codeph>TPtr</codeph>.</p> <p>The
source are literals which are converted to descriptor type.</p> <codeblock id="GUID-86F2890B-6AD2-5637-90B6-469554026C12" xml:space="preserve">_LIT(KText,"Hello World!");
_LIT(KExtraText," &amp; Hi");
...
TBufC&lt;16&gt; buf1(KText);
...
TPtr ptr = buf1.Des();
...
ptr.Delete((ptr.Length()-1),1);
ptr.Append(KExtraText);</codeblock> <p>Define a <codeph>TText</codeph> area
initialised to contain the string "Have a nice day":</p> <p>The following
code fragments show the construction of a <codeph>TPtr</codeph> using a pointer
and specifying a length and a maximum length. This technique is not commonly
used. Literals are a much better way of defining string constants.</p> <codeblock id="GUID-998F1C38-942B-53F5-BBC5-E33781AF1253" xml:space="preserve">TText str[16] =  {'H', 'a', 'v', 'e', ' ', 'a',
    ' ', 'n', 'i', 'c', 'e',
    ' ', 'd', 'a', 'y', '\0'};</codeblock> <codeblock id="GUID-EF4302BB-F536-5B20-B109-1505688B8B60" xml:space="preserve">TPtr ptr(&amp;str[0],15,16);</codeblock> <p>The
descriptor <codeph>ptr</codeph> represents the data in <codeph>str</codeph> and
is constructed to have a current length of 15 (the length of the text, excluding
the zero terminator) and a maximum length of 16 (the actual length of <codeph>str</codeph>).
Once the descriptor has been constructed, it has no further use for the zero
terminator.</p> <codeblock id="GUID-23A4799F-7B57-5B2B-B549-2BD168D208EC" xml:space="preserve">TPtr ptr(&amp;str[0],15,16);</codeblock> </section>
<section id="GUID-AA957AF0-8791-446C-B6E3-DD5EDB642E9E"><title>Replacing data through the TPtr</title> <p>Data can be completely
replaced using the assignment operator or the <xref href="GUID-CD3C9BD5-1386-3CF5-A8F6-9BE1AE40689F.dita"><apiname>Copy()</apiname></xref> function.:</p> <codeblock id="GUID-DBF0A411-CA03-5EAD-AFCD-1617C52C195F" xml:space="preserve">_LIT(KText,"Hi there");
...
ptr = KText;
...
ptr.Copy(KText);</codeblock> <p>Note the use of the <codeph>_LIT</codeph> macro
to define the source string. A literal is converted into a descriptor type.</p> <p>The
length of <codeph>ptr</codeph> is now 8 but the maximum length remains unchanged.
The size depends on the build variant. In a non-Unicode build, this is 8 but
in a Unicode build, this becomes 16 (two bytes for every character).</p> </section>
<section id="GUID-4A13D438-C058-4370-970E-1139708758E3"><title>Changing the length of data</title> <p>The length of the data
represented can be changed. </p> <codeblock id="GUID-0AE02AC5-2E85-5950-894A-FF7B6C8C5856" xml:space="preserve">_LIT(KText,"Hi there");
...
ptr = KText;
ptr.SetLength(2);
ptr.Zero();
</codeblock> <p>For example, after <codeph>ptr.SetLength(2)</codeph>, the
descriptor represents the string "Hi". The length can even be set to zero
so that after <codeph>ptr.Zero()</codeph>, the descriptor represents no data.
Nevertheless, the maximum length remains unchanged.</p> </section>
</conbody><related-links>
<link>
<desc><xref href="GUID-7CB11EAD-260E-551A-85F1-FEAC975FE722.dita">Literal Descriptors</xref></desc>
</link>
</related-links></concept>