--- a/Symbian3/SDK/Source/GUID-BD649ABC-4DBC-5E37-B80D-2BB86F94F26A.dita Fri Jul 16 17:23:46 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-BD649ABC-4DBC-5E37-B80D-2BB86F94F26A.dita Tue Jul 20 12:00:49 2010 +0100
@@ -1,101 +1,97 @@
-<?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-BD649ABC-4DBC-5E37-B80D-2BB86F94F26A" xml:lang="en"><title>How to
-use the non-modifiable buffer descriptor — TBufC<TInt></title><shortdesc>Non-modifiable buffer descriptors are useful for holding constant
-strings or data and providing safe ways to access that data.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
-<ul>
-<li id="GUID-74A075D5-195D-5BB7-BC40-D683635BE6F7"><p>For text data, it is
-usual to construct a <codeph>TBufC<TInt></codeph> type and allow the appropriate
-variant, either a <codeph>TBufC8<TInt></codeph> or a <codeph>TBufC16<TInt></codeph> to
-be selected at build time.</p> </li>
-<li id="GUID-0AA8DD41-55DF-5448-A5D5-DC403E60C3A4"><p>For binary data, an
-explicit <codeph>TBufC8<TInt></codeph> is used.</p> </li>
-<li id="GUID-441D5170-8C00-5BE6-AF0C-44DB149E87F1"><p>It is rare to use an
-explicit <codeph>TBufC16<TInt></codeph>.</p> </li>
-</ul>
-<p>Data cannot be changed through this descriptor although it can be replaced
-using the assignment operators.</p>
-<p>By using the <codeph>Des()</codeph> function to construct a <codeph>TPtr/TPtr8/TPtr16</codeph> modifiable
-pointer descriptor for the buffer's data, it becomes possible to modify that
-data.</p>
-<p>Although, the following notes refer to the build independent types; they
-are equally valid for the explicit 8 bit and 16 bit types.</p>
-<section id="GUID-5591AC50-485E-413D-B3A7-BCE59F3B634D"><title>Constructing a TBufC<TInt></title> <p>A non-modifiable
-buffer descriptor can be constructed in a number of ways:</p> <ul>
-<li id="GUID-8328A45B-EB36-5C80-9B3D-969DA033B71E"><p>as an empty buffer descriptor.</p> </li>
-<li id="GUID-D0CDC7BA-A2A2-5953-8700-F43FF5FD2AE2"><p>by copying data from
-any other type of descriptor.</p> </li>
-<li id="GUID-A7CC00D3-16AB-5D2F-B25E-011D689C3BA9"><p>by copying data from
-another non-modifiable buffer descriptor of the same size.</p> </li>
-</ul> <p>The following code fragment constructs a <codeph>TBufC<16></codeph> object.
-The buffer descriptor is uninitialised, i.e. it contains no data. The assignment
-operator can be used to put data into the buffer descriptor after construction:</p> <codeblock id="GUID-BED8AC0B-4F0B-5859-994B-723F4B8F84A1" xml:space="preserve">_LIT(KText,"Hello World!");
-...
-TBufC<16> buf1; // length of buf1 is 0
-...
-buf1 = KText; // data assigned</codeblock> <p>The following code fragment
-constructs a <codeph>TBufC<16></codeph> object, initialised with the 12
-characters making up the English language phrase "Hello World!".</p> <p>The
-source descriptor is a literal which is converted to descriptor type.</p> <codeblock id="GUID-737E0C5F-AE11-586D-B81C-0E3D1AD96414" xml:space="preserve">_LIT(KText,"Hello World!");
-...
-TBufC<16> buf1(KText); // length of buf1 is 12</codeblock> <p>The following
-code fragment constructs a <codeph>TBufC<16></codeph> object, initialised
-with the content of another <codeph>TBufC<16></codeph> object.</p> <codeblock id="GUID-A8A21448-DBE4-5F68-8CA0-57298E04036C" xml:space="preserve">_LIT(KText,"Hello World!");
-...
-TBufC<16> buf1(KText);
-TBufC<16> buf2(buf1); // data copied from descriptor buf1
- // length of buf2 is 12</codeblock> </section>
-<section id="GUID-1C814D9C-5F53-4885-90B9-B83480CF623E"><title>Replacing data</title> <p>Data within a non-modifiable buffer
-descriptor can be completely replaced by using the assignment operator:</p> <codeblock id="GUID-C3F90B27-EB1C-5864-A80A-0D0C77BB67FC" xml:space="preserve">_LIT(KText,"Hello World!");
-_LIT(KNewText,"New text");
-...
-TBufC<16> buf1(KText);
-TBufC<16> buf2;
-...
-buf2 = buf1; // buf2 now contains "Hello World!"
-...
-buf2 = KNewText; // buf2 now contains "New text".
- // the literal is converted to a descriptor
- // type.</codeblock> <p>To prevent data replacement,
-declare <codeph>buf2</codeph> as const.</p> </section>
-<section id="GUID-5F3BEAB3-B469-4673-A3D8-04DB697B8D0F"><title>Constructing a modifiable pointer descriptor to change the
-data</title> <p>The data contained in non-modifiable buffer descriptor <codeph>TBufC<TInt></codeph> <i>can</i> be
-changed by constructing a <codeph>TPtr</codeph> modifiable pointer descriptor
-using the<codeph>Des()</codeph> member function and then changing the data
-through that <codeph>TPtr</codeph>.</p> <p>The maximum length of the <codeph>TPtr</codeph> is
-the value of the <codeph>TBufC<TInt></codeph> template parameter.</p> <p>The
-following code fragment shows data being changed:</p> <codeblock id="GUID-02B09EBC-3E58-51B1-8D14-E388250A674A" 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>This deletes the last character in <codeph>buf1</codeph> and
-adds the characters " & Hi" so that <codeph>buf1</codeph> now contains
-the text "Hello World & Hi" and its length is 16. Note that the length
-of both <codeph>buf1</codeph> and <codeph>ptr</codeph> change to reflect the
-data that they now both represent.</p> <p>Note that any attempt to append
-more data raises a panic.</p> </section>
-<section id="GUID-9DD4E5D1-B0A0-41BC-AE54-FC062D21173C"><title>Accessing data</title> <p>Once a non-modifiable buffer descriptor
-has been constructed, the functions in the base class, <codeph>TDesC</codeph>,
-are available to access the data.</p> <codeblock id="GUID-CE288FF9-26F7-533D-ADC4-E535035039B2" xml:space="preserve">_LIT(KText,"Hello World!");
-...
-TBufC<16> buf1(KText);
-...</codeblock> <codeblock id="GUID-656150B0-C7DF-54B7-9127-6BE685EEEA83" xml:space="preserve">buf1.Length();</codeblock> </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-BD649ABC-4DBC-5E37-B80D-2BB86F94F26A" xml:lang="en"><title>How to use the non-modifiable buffer descriptor — TBufC<TInt></title><shortdesc>Non-modifiable buffer descriptors are useful for holding
+constant strings or data and providing safe ways to access that data.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<ul>
+<li id="GUID-74A075D5-195D-5BB7-BC40-D683635BE6F7"><p>For text data,
+it is usual to construct a <codeph>TBufC<TInt></codeph> type and
+allow the appropriate variant, either a <codeph>TBufC8<TInt></codeph> or a <codeph>TBufC16<TInt></codeph> to be selected at build time.</p> </li>
+<li id="GUID-0AA8DD41-55DF-5448-A5D5-DC403E60C3A4"><p>For binary data,
+an explicit <codeph>TBufC8<TInt></codeph> is used.</p> </li>
+<li id="GUID-441D5170-8C00-5BE6-AF0C-44DB149E87F1"><p>It is rare to
+use an explicit <codeph>TBufC16<TInt></codeph>.</p> </li>
+</ul>
+<p>Data cannot be changed through this descriptor although it can
+be replaced using the assignment operators.</p>
+<p>By using the <codeph>Des()</codeph> function to construct a <codeph>TPtr/TPtr8/TPtr16</codeph> modifiable pointer descriptor for the
+buffer's data, it becomes possible to modify that data.</p>
+<p>Although, the following notes refer to the build independent types;
+they are equally valid for the explicit 8 bit and 16 bit types.</p>
+<section id="GUID-5591AC50-485E-413D-B3A7-BCE59F3B634D"><title>Constructing
+a TBufC<TInt></title> <p>A non-modifiable buffer descriptor can
+be constructed in a number of ways:</p> <ul>
+<li id="GUID-8328A45B-EB36-5C80-9B3D-969DA033B71E"><p>as an empty
+buffer descriptor.</p> </li>
+<li id="GUID-D0CDC7BA-A2A2-5953-8700-F43FF5FD2AE2"><p>by copying data
+from any other type of descriptor.</p> </li>
+<li id="GUID-A7CC00D3-16AB-5D2F-B25E-011D689C3BA9"><p>by copying data
+from another non-modifiable buffer descriptor of the same size.</p> </li>
+</ul> <p>The following code fragment constructs a <codeph>TBufC<16></codeph> object. The buffer descriptor is uninitialised, i.e. it contains
+no data. The assignment operator can be used to put data into the
+buffer descriptor after construction:</p> <codeblock id="GUID-BED8AC0B-4F0B-5859-994B-723F4B8F84A1" xml:space="preserve">_LIT(KText,"Hello World!");
+...
+TBufC<16> buf1; // length of buf1 is 0
+...
+buf1 = KText; // data assigned</codeblock> <p>The following code
+fragment constructs a <codeph>TBufC<16></codeph> object, initialised
+with the 12 characters making up the English language phrase "Hello
+World!".</p> <p>The source descriptor is a literal which is converted
+to descriptor type.</p> <codeblock id="GUID-737E0C5F-AE11-586D-B81C-0E3D1AD96414" xml:space="preserve">_LIT(KText,"Hello World!");
+...
+TBufC<16> buf1(KText); // length of buf1 is 12</codeblock> <p>The following code fragment constructs a <codeph>TBufC<16></codeph> object, initialised with the content of another <codeph>TBufC<16></codeph> object.</p> <codeblock id="GUID-A8A21448-DBE4-5F68-8CA0-57298E04036C" xml:space="preserve">_LIT(KText,"Hello World!");
+...
+TBufC<16> buf1(KText);
+TBufC<16> buf2(buf1); // data copied from descriptor buf1
+ // length of buf2 is 12</codeblock> </section>
+<section id="GUID-1C814D9C-5F53-4885-90B9-B83480CF623E"><title>Replacing
+data</title> <p>Data within a non-modifiable buffer descriptor can
+be completely replaced by using the assignment operator:</p> <codeblock id="GUID-C3F90B27-EB1C-5864-A80A-0D0C77BB67FC" xml:space="preserve">_LIT(KText,"Hello World!");
+_LIT(KNewText,"New text");
+...
+TBufC<16> buf1(KText);
+TBufC<16> buf2;
+...
+buf2 = buf1; // buf2 now contains "Hello World!"
+...
+buf2 = KNewText; // buf2 now contains "New text".
+ // the literal is converted to a descriptor
+ // type.</codeblock> <p>To prevent data
+replacement, declare <codeph>buf2</codeph> as const.</p> </section>
+<section id="GUID-5F3BEAB3-B469-4673-A3D8-04DB697B8D0F"><title>Constructing
+a modifiable pointer descriptor to change the data</title> <p>The
+data contained in non-modifiable buffer descriptor <codeph>TBufC<TInt></codeph> <i>can</i> be changed by constructing a <codeph>TPtr</codeph> modifiable
+pointer descriptor using the<codeph>Des()</codeph> member function
+and then changing the data through that <codeph>TPtr</codeph>.</p> <p>The maximum length of the <codeph>TPtr</codeph> is the value
+of the <codeph>TBufC<TInt></codeph> template parameter.</p> <p>The following code fragment shows data being changed:</p> <codeblock id="GUID-02B09EBC-3E58-51B1-8D14-E388250A674A" 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>This deletes the last character in <codeph>buf1</codeph> and adds the characters " & Hi" so that <codeph>buf1</codeph> now contains the text "Hello World & Hi" and
+its length is 16. Note that the length of both <codeph>buf1</codeph> and <codeph>ptr</codeph> change to reflect the data that they now
+both represent.</p> <p>Note that any attempt to append more data raises
+a panic.</p> </section>
+<section id="GUID-9DD4E5D1-B0A0-41BC-AE54-FC062D21173C"><title>Accessing
+data</title> <p>Once a non-modifiable buffer descriptor has been constructed,
+the functions in the base class, <codeph>TDesC</codeph>, are available
+to access the data.</p> <codeblock id="GUID-CE288FF9-26F7-533D-ADC4-E535035039B2" xml:space="preserve">_LIT(KText,"Hello World!");
+...
+TBufC<16> buf1(KText);
+...</codeblock> <codeblock id="GUID-656150B0-C7DF-54B7-9127-6BE685EEEA83" xml:space="preserve">buf1.Length();</codeblock> </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