<?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() >= 8);

    s.Compress();

    test(s.MaxLength() >= 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& 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>