LString Tutorial

Steps

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