--- a/Symbian3/SDK/Source/GUID-E81D72B2-BA77-5F4E-8742-3812A60A4DAC.dita Fri Jul 16 17:23:46 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-E81D72B2-BA77-5F4E-8742-3812A60A4DAC.dita Tue Jul 20 12:00:49 2010 +0100
@@ -1,106 +1,101 @@
-<?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-E81D72B2-BA77-5F4E-8742-3812A60A4DAC" xml:lang="en"><title>How to
-use modifiable buffer descriptor — TBuf<TInt></title><shortdesc>Modifiable buffer descriptors are useful for holding strings or
-data and providing safe ways to access and modify that data.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
-<ul>
-<li id="GUID-F276E9FE-B839-54ED-9F50-8E45CB094922"><p>For text data, it is
-usual to construct a <codeph>TBuf<TInt></codeph> type and allow the appropriate
-variant, either a <codeph>TBuf8<TInt></codeph> or a <codeph>TBuf16<TInt></codeph> to
-be selected at build time.</p> </li>
-<li id="GUID-9860DB57-62C3-5295-B00E-5F629771FED9"><p>For binary data, an
-explicit <codeph>TBuf8<TInt></codeph> is used.</p> </li>
-<li id="GUID-34C95FAB-0F58-5B61-B9FC-A31588855F96"><p>It is rare to use an
-explicit <codeph>TBuf16<TInt></codeph>.</p> </li>
-</ul>
-<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-824524FB-98B7-4CDA-A3FD-233C7C0DDD5F"><title>Constructing
-a TBuf<TInt></title> <p>A modifiable buffer descriptor can be constructed
-in a number of ways:</p> <ul>
-<li id="GUID-BCFAA769-D038-5A09-B6BF-586C93F08B0B"><p>as an empty buffer descriptor.</p> </li>
-<li id="GUID-9DE61358-D6B9-54CA-9FED-11AC29443093"><p>as an empty buffer descriptor
-but giving it a length.</p> </li>
-<li id="GUID-50FB7967-79C8-5F8C-8569-36B40D14894E"><p>by copying data from
-any other type of descriptor.</p> </li>
-<li id="GUID-26E1FDDC-F0BB-5441-8F81-EF2CFA61787A"><p>by copying data from
-another modifiable buffer descriptor of the same size.</p> </li>
-</ul> <p>The following code fragment constructs a <codeph>TBuf<16></codeph> object.
-The buffer descriptor is uninitialised, i.e. it contains no data. The assignment
-operator or the <codeph>Copy()</codeph> function can be used to put data into
-the buffer descriptor after construction:</p> <codeblock id="GUID-01CA390C-ECC4-56C2-A1F6-F62C2AA75E57" xml:space="preserve">_LIT(KText,"Hello World!");
-...
-TBuf<16> buf1; // length of buf1 is 0
-...
-buf1 = KText; // data assigned</codeblock> <p>The source descriptor is a
-literal which is converted to descriptor type.</p> <p>The following code fragment
-constructs a <codeph>TBuf<16></codeph> object and sets it length to 12.
-No data is assigned into the descriptor.</p> <codeblock id="GUID-FA8A1FE8-7809-5E28-B3EB-420B405DDC32" xml:space="preserve">...
-TBuf<16> buf1(12); // length of buf1 is 12
-...</codeblock> <p>The following code fragment constructs a <codeph>TBuf<16></codeph> object,
-initialised with the 12 characters making up the English language phrase "Hello
-World!".</p> <codeblock id="GUID-74B4614D-4273-5F9E-8A2D-1E9A8A3960D8" xml:space="preserve">_LIT(KText,"Hello World!");
-...
-TBuf<16> buf1(KText);</codeblock> <p>The following code fragment constructs
-a <codeph>TBuf<16></codeph> object from another <codeph>TBuf<16></codeph> object.
-This is, in effect, copy construction.</p> <codeblock id="GUID-BE55436F-FDB8-5768-947F-801D02FDA631" xml:space="preserve">_LIT(KText,"Hello World!");
-...
-TBuf<16> buf1(KText);
-TBuf<16> buf2(buf1); // buf2 constructed from the data in buf1</codeblock> <p>In
-both of these cases, the resulting length of the descriptor is 12.</p> <p>A
-non-modifiable buffer descriptor can also be constructed from 'C' style zero
-terminated string. However, this is rarely necessary but may make it easier
-to port legacy 'C' code.</p> </section>
-<section id="GUID-8A534041-1730-43FB-8FCD-4C5BFDAAE730"><title>Replacing data</title> <p>Data
-within a modifiable buffer descriptor can be completely replaced through the
-assignment operator or by using the <codeph>Copy()</codeph> function.</p> <codeblock id="GUID-D990C115-DD84-5E04-89DA-F483A63D03FA" xml:space="preserve">_LIT(KText,"Hello World!");
-_LIT(KNewText,"New text");
-_LIT(KReplaced,"Replaced");
-...
-TBuf<16> buf1(KText);
-TBuf<16> buf2;
-...
-buf2 = buf1; // buf2 now contains "Hello World!"
-...
-buf2 = KNewText; // buf2 now contains "New text".
- // the literal is converted to a descriptor
- // type.
-buf2.Copy(KReplaced); // buf2 content replaced using Copy()</codeblock> </section>
-<section id="GUID-E49444E0-457E-4645-A1D5-C350FF998F9A"><title>Accessing and
-changing data</title> <p>Once a modifiable buffer descriptor has been constructed,
-the functions in the base classes, <codeph>TDesC</codeph> and <codeph>TDes</codeph>,
-are available to be access and change the data.</p> <codeblock id="GUID-386035F7-1C0F-5CB3-BA5B-5E0EF18DF6F8" xml:space="preserve">_LIT(KText,"Hello World!");
-...
-TBufC<16> buf1(KText);
-...
-buf1.Length();</codeblock> <p>and</p> <codeblock id="GUID-7BCC4118-4294-5607-A92B-5DBA9E68CBEE" xml:space="preserve">_LIT(KText,"Hello World!");
-...
-TBufC<16> buf1(KText); // length is 12
-...
-buf1.Delete(6,6); // length is now 6, leaving "Hello" in
- // the buffer</codeblock> </section>
-<section id="GUID-970BCE5F-CC4D-4F60-91A9-6107975E9C3F"><title>Illegal access
-causing an exception</title> <p>The following code fragment raises a panic
-because of an attempt to assign too much data. The maximum length of the buffer
-descriptor is 16 but the length of the data to be copied is 31:</p> <codeblock id="GUID-38DC46A1-E2A0-52DD-A821-F0D6B2C45430" xml:space="preserve">_LIT(KText,"Hello World! The sun is shining");
-...
-TBufC<16> buf1(KText);</codeblock> <p>The following code fragment raises
-a panic because of an attempt to delete data outside the boundary defined
-by the descriptor:</p> <codeblock id="GUID-71FB3EFC-BFBA-5072-ADD2-3471E2A08D0C" xml:space="preserve">_LIT(KText,"Hello World!");
-...
-TBufC<16> buf1(KText);
-buf1.Delete(99,1);</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-E81D72B2-BA77-5F4E-8742-3812A60A4DAC" xml:lang="en"><title>How to use modifiable buffer descriptor — TBuf<TInt></title><shortdesc>Modifiable buffer descriptors are useful for holding strings
+or data and providing safe ways to access and modify that data.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<ul>
+<li id="GUID-F276E9FE-B839-54ED-9F50-8E45CB094922"><p>For text data,
+it is usual to construct a <codeph>TBuf<TInt></codeph> type and
+allow the appropriate variant, either a <codeph>TBuf8<TInt></codeph> or a <codeph>TBuf16<TInt></codeph> to be selected at build time.</p> </li>
+<li id="GUID-9860DB57-62C3-5295-B00E-5F629771FED9"><p>For binary data,
+an explicit <codeph>TBuf8<TInt></codeph> is used.</p> </li>
+<li id="GUID-34C95FAB-0F58-5B61-B9FC-A31588855F96"><p>It is rare to
+use an explicit <codeph>TBuf16<TInt></codeph>.</p> </li>
+</ul>
+<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-824524FB-98B7-4CDA-A3FD-233C7C0DDD5F"><title>Constructing
+a TBuf<TInt></title> <p>A modifiable buffer descriptor can be constructed
+in a number of ways:</p> <ul>
+<li id="GUID-BCFAA769-D038-5A09-B6BF-586C93F08B0B"><p>as an empty
+buffer descriptor.</p> </li>
+<li id="GUID-9DE61358-D6B9-54CA-9FED-11AC29443093"><p>as an empty
+buffer descriptor but giving it a length.</p> </li>
+<li id="GUID-50FB7967-79C8-5F8C-8569-36B40D14894E"><p>by copying data
+from any other type of descriptor.</p> </li>
+<li id="GUID-26E1FDDC-F0BB-5441-8F81-EF2CFA61787A"><p>by copying data
+from another modifiable buffer descriptor of the same size.</p> </li>
+</ul> <p>The following code fragment constructs a <codeph>TBuf<16></codeph> object. The buffer descriptor is uninitialised, i.e. it contains
+no data. The assignment operator or the <codeph>Copy()</codeph> function
+can be used to put data into the buffer descriptor after construction:</p> <codeblock id="GUID-01CA390C-ECC4-56C2-A1F6-F62C2AA75E57" xml:space="preserve">_LIT(KText,"Hello World!");
+...
+TBuf<16> buf1; // length of buf1 is 0
+...
+buf1 = KText; // data assigned</codeblock> <p>The source descriptor
+is a literal which is converted to descriptor type.</p> <p>The following
+code fragment constructs a <codeph>TBuf<16></codeph> object and
+sets it length to 12. No data is assigned into the descriptor.</p> <codeblock id="GUID-FA8A1FE8-7809-5E28-B3EB-420B405DDC32" xml:space="preserve">...
+TBuf<16> buf1(12); // length of buf1 is 12
+...</codeblock> <p>The following code fragment constructs a <codeph>TBuf<16></codeph> object, initialised with the 12 characters making
+up the English language phrase "Hello World!".</p> <codeblock id="GUID-74B4614D-4273-5F9E-8A2D-1E9A8A3960D8" xml:space="preserve">_LIT(KText,"Hello World!");
+...
+TBuf<16> buf1(KText);</codeblock> <p>The following code fragment
+constructs a <codeph>TBuf<16></codeph> object from another <codeph>TBuf<16></codeph> object. This is, in effect, copy construction.</p> <codeblock id="GUID-BE55436F-FDB8-5768-947F-801D02FDA631" xml:space="preserve">_LIT(KText,"Hello World!");
+...
+TBuf<16> buf1(KText);
+TBuf<16> buf2(buf1); // buf2 constructed from the data in buf1</codeblock> <p>In both of these cases, the resulting length of the descriptor
+is 12.</p> <p>A non-modifiable buffer descriptor can also be constructed
+from 'C' style zero terminated string. However, this is rarely necessary
+but may make it easier to port legacy 'C' code.</p> </section>
+<section id="GUID-8A534041-1730-43FB-8FCD-4C5BFDAAE730"><title>Replacing
+data</title> <p>Data within a modifiable buffer descriptor can be
+completely replaced through the assignment operator or by using the <codeph>Copy()</codeph> function.</p> <codeblock id="GUID-D990C115-DD84-5E04-89DA-F483A63D03FA" xml:space="preserve">_LIT(KText,"Hello World!");
+_LIT(KNewText,"New text");
+_LIT(KReplaced,"Replaced");
+...
+TBuf<16> buf1(KText);
+TBuf<16> buf2;
+...
+buf2 = buf1; // buf2 now contains "Hello World!"
+...
+buf2 = KNewText; // buf2 now contains "New text".
+ // the literal is converted to a descriptor
+ // type.
+buf2.Copy(KReplaced); // buf2 content replaced using Copy()</codeblock> </section>
+<section id="GUID-E49444E0-457E-4645-A1D5-C350FF998F9A"><title>Accessing
+and changing data</title> <p>Once a modifiable buffer descriptor has
+been constructed, the functions in the base classes, <codeph>TDesC</codeph> and <codeph>TDes</codeph>, are available to be access and change
+the data.</p> <codeblock id="GUID-386035F7-1C0F-5CB3-BA5B-5E0EF18DF6F8" xml:space="preserve">_LIT(KText,"Hello World!");
+...
+TBufC<16> buf1(KText);
+...
+buf1.Length();</codeblock> <p>and</p> <codeblock id="GUID-7BCC4118-4294-5607-A92B-5DBA9E68CBEE" xml:space="preserve">_LIT(KText,"Hello World!");
+...
+TBufC<16> buf1(KText); // length is 12
+...
+buf1.Delete(6,6); // length is now 6, leaving "Hello" in
+ // the buffer</codeblock> </section>
+<section id="GUID-970BCE5F-CC4D-4F60-91A9-6107975E9C3F"><title>Illegal
+access causing an exception</title> <p>The following code fragment
+raises a panic because of an attempt to assign too much data. The
+maximum length of the buffer descriptor is 16 but the length of the
+data to be copied is 31:</p> <codeblock id="GUID-38DC46A1-E2A0-52DD-A821-F0D6B2C45430" xml:space="preserve">_LIT(KText,"Hello World! The sun is shining");
+...
+TBufC<16> buf1(KText);</codeblock> <p>The following code fragment
+raises a panic because of an attempt to delete data outside the boundary
+defined by the descriptor:</p> <codeblock id="GUID-71FB3EFC-BFBA-5072-ADD2-3471E2A08D0C" xml:space="preserve">_LIT(KText,"Hello World!");
+...
+TBufC<16> buf1(KText);
+buf1.Delete(99,1);</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