<?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 xml:lang="en" id="GUID-01677FF9-8FA1-5F0D-8223-46EDD20E3075"><title>LString</title><prolog><metadata><keywords/></metadata></prolog><conbody><p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita"><apiname> LString</apiname></xref> is a convenient, general-purpose string class derived from <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref>. LString adds automatic cleanup and on-demand buffer resize facilities. Like an <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref>, 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> <section><title>Need for LString</title> <p>While being simpler to use than existing descriptors in many cases, LString's use of heap allocation and it’s resizing variant methods clearly come with associated costs. Their use in performance-critical code should be carefully considered. On the other hand, LString's small stack footprint and ability to better-handle inputs of unpredictable size may make them a better choice when the alternative is a large, fixed-max-size <xref href="GUID-0B9C8884-6BFF-35E2-AA6F-E4057B85AFCF.dita"><apiname>TBuf</apiname></xref> or <xref href="GUID-A103FB19-60B3-3E45-97A5-1F295934ACA1.dita"><apiname>HBufC</apiname></xref>. </p> </section> <section><title>Variants of LString</title> <p>The concrete <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita"><apiname>LString </apiname></xref> classes provided are <xref href="GUID-C788743B-AD3C-3508-83CD-942EFA243B26.dita"><apiname>LString8</apiname></xref> and <xref href="GUID-C5A68FFA-9AED-319D-B29D-723F9AA7FFD7.dita"><apiname>LString16</apiname></xref> for 8 and 16 bit data respectively. Two convenient Typedefs are also provided: </p> <p>LString for <xref href="GUID-C5A68FFA-9AED-319D-B29D-723F9AA7FFD7.dita"><apiname>LString16</apiname></xref> and LData for <xref href="GUID-C788743B-AD3C-3508-83CD-942EFA243B26.dita"><apiname>LString8</apiname></xref>  </p> </section> <section><title> Library and header file</title> <p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita"><apiname>LString</apiname></xref> is part of the EUser High Level library which is found in <xref href="GUID-6A6706AB-8859-3D2C-90B2-EE9E20B494BE.dita"><apiname>euserhl.dll</apiname></xref>. To use <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita"><apiname>LString</apiname></xref> you must link <filepath>euserhl.lib</filepath> library and include <filepath>estring.h</filepath> header file. </p> </section> <section><title> Characteristics of LString</title> <p>The following are the characteristics of LString: </p> <ul><li id="GUID-BD07F012-83A8-5A10-964C-DA710D73CAD9"><p> <b>Automatic in-place resizing:</b> LString replaces standard descriptor APIs with a corresponding leaving method that automatically expands the underlying buffer on-demand. </p> </li> <li id="GUID-986A6AD5-E6F4-51E1-B6CB-5B2E58A19954"><p> <b>Automatic Growth:</b> LString supports automatic growth when being manipulated directly as an LString. When an LString is passed to a function accepting a <xref href="GUID-AD7087EB-7922-3959-8C3C-D31B09A77540.dita"><apiname>TDes()</apiname></xref> that function will operate on it as if it is a fixed-max-length descriptor. </p> </li> <li id="GUID-DAC97247-345B-5E11-8E32-1A08920CB765"><p> <b>Compression:</b> It is difficult to predict the use of an LString object and therefore auto-compression would likely result in further allocations and be inefficient. If compression is desired this must be done manually via <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita#GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC/GUID-48151B50-C8C4-3011-9A76-8242EB7E1DDC"><apiname>LString::Compress()</apiname></xref>. </p> </li> </ul> </section> <section><title>LString APIs</title> <p>The following are the LString APIs: </p> <ul><li id="GUID-44F43752-D692-5A53-AFD9-D0F81C21ECD0"><p> <xref href="GUID-B7878C32-D093-3B15-A5B6-E91DA3A0961E.dita"><apiname>SetMaxLengthL()</apiname></xref>  </p> <codeblock id="GUID-507C3A66-1670-5AC4-88EE-FA84D1D1E08F" xml:space="preserve">void LStringX::SetMaxLength(TInt aMaxLength)</codeblock> <p> <b>Description:</b> This method sets the storage space allocated to this descriptor to the specified value by growing or compressing its buffer size. If the current length of the descriptor is greater than the specified max length, length is truncated to max length. </p> </li> <li id="GUID-29DA153C-459B-5ADD-919F-4BBCD50B0116"><p> <xref href="GUID-A3EE1898-D58C-3C15-8A98-7BEF85963AEB.dita"><apiname>ReserveFreeCapacityL()</apiname></xref>  </p> <codeblock id="GUID-54E2FE69-15A5-505C-A6D2-0E4217BF5359" xml:space="preserve">void LStringX::ReserveFreeCapacityL(TInt aExtraSpaceRequired)</codeblock> <p> <b>Description:</b> This method ensures that the remaining unused space is more than the supplied value. It may reallocate a larger storage space to meet the requirement. As a result MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated. </p> </li> <li id="GUID-A75B4E77-51ED-5F83-AAB8-234C6D184C68"><p> <xref href="GUID-E016AEA6-D901-3AF4-AE52-CBE4308E962C.dita"><apiname>Compress()</apiname></xref>  </p> <codeblock id="GUID-33D642D8-E1A0-5004-A014-334DF9E2B7BE" xml:space="preserve">void LStringX::Compress()</codeblock> <p> <b>Description:</b> This method re-allocates a smaller descriptor buffer space to the current descriptor length. This may cause the string descriptor's heap buffer to be reallocated in order to accommodate the new data. As a result, MaxLength() and Ptr() may return different values afterwards, and any existing raw pointers to into the descriptor data may be invalidated. </p> </li> <li id="GUID-0824D4AC-6978-5455-B65F-06CEAB3A0CEF"><p> <xref href="GUID-ABC0096D-A6DD-3AAA-8AA6-57474737983A.dita"><apiname>Reset()</apiname></xref>  </p> <codeblock id="GUID-ACA006B1-ED9B-5EB9-BFA5-9249354D6399" xml:space="preserve">void LStringX::Reset()</codeblock> <p> <b>Description:</b> This method re-initialises the descriptor destroying its payload. </p> </li> </ul> </section> <section><title>See Also</title> <p><xref href="GUID-B007634D-4D55-528A-8B85-6120C633AC8B.dita">EUser High Level Library Overview</xref>  </p> <p><xref href="GUID-D33EB877-CCCB-527B-8AFC-4A8385C55E78.dita">EUser High Level Library Tutorials</xref>  </p> </section> </conbody></concept>