<?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," & Hi");

...

TBufC<16> 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>