Collapse all Symbian^3 Product Developer Library

LString

LString 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 TDes or a TDesC reference. Again like an RBuf, an LString maintains its string data in a heap buffer.

Need for LString

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 TBuf or HBufC.

Variants of LString

The concrete LString classes provided are LString8 and LString16 for 8 and 16 bit data respectively. Two convenient Typedefs are also provided:

LString for LString16 and LData for LString8

Library and header file

LString is part of the EUser High Level library which is found in euserhl.dll. To use LString you must link euserhl.lib library and include estring.h header file.

Characteristics of LString

The following are the characteristics of LString:

Automatic in-place resizing: LString replaces standard descriptor APIs with a corresponding leaving method that automatically expands the underlying buffer on-demand.
Automatic Growth: LString supports automatic growth when being manipulated directly as an LString. When an LString is passed to a function accepting a TDes() that function will operate on it as if it is a fixed-max-length descriptor.
Compression: 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 LString::Compress().

LString APIs

The following are the LString APIs:

SetMaxLengthL()
```
void LStringX::SetMaxLength(TInt aMaxLength)
```
Description: 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.
ReserveFreeCapacityL()
```
void LStringX::ReserveFreeCapacityL(TInt aExtraSpaceRequired)
```
Description: 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.
Compress()
```
void LStringX::Compress()
```
Description: 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.
Reset()
```
void LStringX::Reset()
```
Description: This method re-initialises the descriptor destroying its payload.