--- a/Symbian3/SDK/Source/GUID-F46D5A5B-EC44-53B0-9A11-886735B28610.dita Fri Jul 16 17:23:46 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-F46D5A5B-EC44-53B0-9A11-886735B28610.dita Tue Jul 20 12:00:49 2010 +0100
@@ -1,87 +1,81 @@
-<?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<TInt></codeph>, using
-the <codeph>Des()</codeph> function. Data that would normally be unmodifiable
-through the <codeph>TBufC<TInt></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(&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(&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>
+<?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<TInt></codeph>, using the <codeph>Des()</codeph> function. Data that would normally
+be unmodifiable through the <codeph>TBufC<TInt></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(&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(&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>
\ No newline at end of file