--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-7984F8F7-DC7B-56E0-A5DA-071A3D87714A.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,123 @@
+<?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 task
+  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
+<task id="GUID-7984F8F7-DC7B-56E0-A5DA-071A3D87714A" xml:lang="en"><title>LString
+Tutorial</title><abstract><p>LStrings can be used as class member variables, declared in the
+class declaration and instantiated in ConstructL(), in the constructor or
+in the constructor initialisation list.  </p></abstract><prolog><metadata><keywords/></metadata></prolog><taskbody>
+<prereq><p><b>Required background</b></p><p>Before beginning you must know
+the following: </p> <ul>
+<li id="GUID-F16B6935-EAF1-5EF1-A69E-4D0D5F48EF95"><p> <xref href="GUID-49D4E917-57EA-39AE-8941-144AA8AC2584.dita"><apiname>TDes </apiname></xref> -
+Build independent modifiable descriptor. </p> </li>
+<li id="GUID-FD3CD5F7-E991-5003-B595-15139EE34880"><p> <xref href="GUID-52D07F46-2162-380C-A775-C3BB335C42F5.dita"><apiname>TDesC </apiname></xref> -
+Build independent non-modifiable descriptor. </p> </li>
+<li id="GUID-0CD1486E-0B54-5877-91D8-7D5C094B90FD"><p> <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> -
+This class provides a buffer that contains, accesses and manipulates TUint16
+data. The buffer itself is on the heap, and is managed by the class. </p> </li>
+</ul> </prereq>
+<context><p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita"><apiname>LString</apiname></xref> is a convenient, general-purpose string
+class derived from RBuf. LString adds automatic cleanup and on-demand buffer
+resize facilities. Like an RBuf, an LString can be passed to any function
+that is prototyped to take a <xref href="GUID-49D4E917-57EA-39AE-8941-144AA8AC2584.dita"><apiname>TDes</apiname></xref> or a <xref href="GUID-52D07F46-2162-380C-A775-C3BB335C42F5.dita"><apiname>TDesC</apiname></xref> reference.
+Again like an <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref>, an LString maintains its string data
+in a heap buffer. </p> </context>
+<steps-unordered>
+<step id="GUID-3B84AF07-5356-4BFA-91D2-B8FE64121852"><cmd><b>Declaring an LString</b></cmd>
+<info><p>LStrings can also be used as class member variables, declared in
+the class declaration and instantiated in <xref href="GUID-C8E0575D-5A7F-3D00-9BE5-AD8D6DBCF2F7.dita"><apiname>ConstructL()</apiname></xref>,
+in the constructor or in the constructor initialisation list. </p> <p>LString
+provides a variety of construction options as show in code snippet below: </p> <codeblock id="GUID-760C7BA0-DDBC-5B8C-AD1C-E0E5E7ECCC1D" xml:space="preserve">
+{
+
+_LIT(KOne, "One ");
+_LIT(KTesting, "Testing ");
+
+
+// A default constructed LString starts empty, doesn't
+// allocate any memory on the heap, and therefore the
+// following cannot leave
+LString s;
+
+// You can initialize with a MaxLength value
+LString s(KMaxFileName); // This operation may leave
+
+// You can initialize from any descriptor (or literal) and the
+// string data is copied into the LString
+LString s(KOne); // From a literal
+
+LString half(s.Left(s.Length() / 2)); // Left returns a TPtrC
+
+// On the other hand, you can initialize from a returned
+// HBufC* and the LString automatically takes ownership
+LString own(AllocateNameL(KTesting));
+
+// LStrings can be allocated on the heap if necessary
+LString* s = new(ELeave) LString;
+
+}
+</codeblock></info>
+</step>
+<step id="GUID-2A0AB10A-433B-46BC-A636-86CC128B6F35"><cmd><b>Managing the size of the LString manually</b></cmd>
+<info><p>Although <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita"><apiname>LString</apiname></xref> supports automatic resizing,
+it is also possible, and sometimes necessary to manually change the length
+of the string. When an LString is passed to a function as a <xref href="GUID-49D4E917-57EA-39AE-8941-144AA8AC2584.dita"><apiname>TDes</apiname></xref> or <xref href="GUID-52D07F46-2162-380C-A775-C3BB335C42F5.dita"><apiname>TDesC</apiname></xref>,
+it looses its automatic resizing capabilities and therefore care must be taken
+to ensure sufficient space is allocated before the call is made. </p> <p>Extra
+space can be allocated to the LString by calling <xref href="GUID-A3EE1898-D58C-3C15-8A98-7BEF85963AEB.dita"><apiname>ReserveFreeCapacityL()</apiname></xref> function
+and the string can be compressed to the minimum length by calling <xref href="GUID-E016AEA6-D901-3AF4-AE52-CBE4308E962C.dita"><apiname>Compress()</apiname></xref> function.
+An example code snippet is shown below: </p> <codeblock id="GUID-DE899D49-DC9D-53DE-8E7B-B0F19EAF4D8A" xml:space="preserve">
+_LIT(KOne, "One ");
+
+{
+    LString s(KOne);
+    s.ReserveFreeCapacityL(4);
+    test(s.Length() == 4);
+    test(s.MaxLength() &gt;= 8);
+    s.Compress();
+    test(s.MaxLength() &gt;= 4);    //note indefinite test
+    s.Reset();
+    test(s.Length() == 0);
+    test(s.MaxLength() == 0);
+}
+</codeblock></info>
+</step>
+<step id="GUID-5FD35D1B-B252-4266-BCC0-7FC00ED6BF93"><cmd><b>Passing an LString to a function expecting a TDes or TDesC</b></cmd>
+<info><p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita"><apiname>LString</apiname></xref>, derived from <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> can
+be passed directly to any method accepting a <xref href="GUID-49D4E917-57EA-39AE-8941-144AA8AC2584.dita"><apiname>TDes</apiname></xref> or <xref href="GUID-52D07F46-2162-380C-A775-C3BB335C42F5.dita"><apiname>TDesC</apiname></xref> parameter.
+Be aware though that once passed as a TDes, LString loses its automatic resizing
+capability. Care must be taken to ensure that sufficient capacity is reserved
+by calling <xref href="GUID-A3EE1898-D58C-3C15-8A98-7BEF85963AEB.dita"><apiname>ReserveFreeCapacityL()</apiname></xref> function or <xref href="GUID-B7878C32-D093-3B15-A5B6-E91DA3A0961E.dita"><apiname>SetMaxLengthL() </apiname></xref> function
+before passing the LString as a TDes. When passed to a function as a TDes
+a USER 11 panic will be raised if the string is modified and the resulting
+length of this descriptor is greater than its maximum length. </p> <p>An example
+code snippet is shown below: </p> <codeblock id="GUID-2BDE3A6B-E974-5E30-AB1A-D670C64AD2F1" xml:space="preserve">
+void GetCurrentPath(TDes&amp; aDes)
+    {
+    aDes = KPath;
+    }
+. . .
+{
+    LString s;
+    test(s.MaxLength() == 0);
+    s.SetMaxLengthL(KMaxFileName);
+    GetCurrentPath(s);
+}
+</codeblock></info>
+</step>
+</steps-unordered>
+</taskbody><related-links>
+<link href="GUID-B1D5B680-00E3-5702-985A-94256180E2D8.dita"><linktext>Automatic
+Resource Management</linktext></link>
+<link href="GUID-69D916D3-ED05-58DA-BA42-CE4D7E4F6482.dita"><linktext>Automatic
+Resource Management Class Templates Tutorial</linktext></link>
+<link href="GUID-B419D99E-8312-5336-9693-3ED8DFCD0559.dita"><linktext>Automatic
+Resource Management Tutorial</linktext></link>
+</related-links></task>
\ No newline at end of file