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.
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.
- Declaring an LString
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;
}
- Managing the size of the LString manually
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);
}
- Passing an LString to a function expecting a TDes or TDesC
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);
}