<?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>