LString Tutorial

LStrings can also be used as class member variables, declared in the class declaration and instantiated in ConstructL(), in the constructor or in the constructor initialisation list.

LString provides a variety of construction options as show in code snippet below:

{

_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;

}

Although LString 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 TDes or TDesC, it looses its automatic resizing capabilities and therefore care must be taken to ensure sufficient space is allocated before the call is made.

Extra space can be allocated to the LString by calling ReserveFreeCapacityL() function and the string can be compressed to the minimum length by calling Compress() function. An example code snippet is shown below:

_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);
}

LString, derived from RBuf can be passed directly to any method accepting a TDes or TDesC 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 ReserveFreeCapacityL() function or SetMaxLengthL() 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.

An example code snippet is shown below:

void GetCurrentPath(TDes& aDes)
    {
    aDes = KPath;
    }
. . .
{
    LString s;
    test(s.MaxLength() == 0);
    s.SetMaxLengthL(KMaxFileName);
    GetCurrentPath(s);
}