<?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 href="GUID-7CB11EAD-260E-551A-85F1-FEAC975FE722.dita"><linktext>Literal
Descriptors</linktext></link>
</related-links></concept>