Introduction

When I was new to Symbian, The first thing that I encountered is Symbian OS String handling and Manipulations. It was then day(s) of nightmare that struck me :). What I found that its bit tricky to remember the descriptor stuffs, but once you get the trick it's easy. No I am not kidding...

So here I am trying to explain how I learned the basic symbian OS string handling and try to remember the things. I will not go here on the war of words whether having descriptors is a good approach or not, because be it be good or bad you have to use it :(. Another thing I will not discuss here is how you can do similar thing using plain C++ or how to do something you can do with plain C++ string manipulation techniques. This article is just regarding descriptors.

The prerequisite of this article is working knowledge of the Symbian OS.

Background

The very first thing you need to do is to remember the descriptor hierarchy. This is very important as all of the 5 descriptors you are going to use derived from some classes and you must know from which class this derives to be able to successfully decide which particular descriptor to use in which scenario. I am not going to explain what a buffer descriptor and Heap Descriptor means, and also what is meant by modifiable and non modifiable descriptors. I believe you must be having enough information on what is meant by above terminologies. I will also not use 8 and 16 bit variant as functionality wise there is a similarity between these two and also not important in understanding the descriptors. The Symbian Descriptor Hierarchy looks something like. (Sorry for not providing fabulous pictures of Descriptor hierarchy). You can have a look at String and Descriptors for picture.

Usage of TPtrC<n>

If we want a literal meaning for this, then it will be "Pointer to a Data that cannot be manipulated" The basic thing to remember about TPtrC<n> is that it contains no manipulation functionalities of its own and it just contains constructors and set methods, and since it derives directly from the TDesC it contains all the functionalities of TDesC.

The pointer will point to data in one of the two ways:
  Create an empty TPtrC and then point it to some data using Set(...) functions.
  Pass the data while constructing by using any one of the overloaded constructors. Let see the above statements with the help of few examples below.

Example 1: Getting TPtrC from TBuf and TBufC

 
Example 2: Getting TPtrC from TText*

The Example Below uses TText16.

 
Example 3: Getting TPtrC from Another TPtrC

You can easily assign one TPtrC to another.

 
Example 4: Getting TText * from TPtrC We can get the TText * from TPtrC by using the Ptr() member

Usage of TBufC<n>

The examples used to describe the working TPtrC gives some understanding about the usage of TBufC<n>, Nevertheless here are few examples on how to create TBufC<n>.

Example 5: Instantiating the TBufC

TBufC<n> is used generally for Text data. For Binary Data explicit TBufC8<n> is used. Though TBufC<n> means that the Data cannot be modified ('C' stands for Constant), but there are two ways by which this data can be modified:
  The Data can be replaced by using assignment operator.
  By using Des() function to construct a TPtr modifiable pointer descriptor for the buffers data. Let see the first way to change the contents of TBufC<n>:

 
Example 6: Changing the contents of TBufC

Another way of changing the contents of TBufC<n> by using the Des() member. This member function returns TPtr modifiable Pointer descriptor using members of the TPtr. The maximum length of the TPtr is the value of the TBufC<n> template parameter. All the manipulating Functions are from TDesC base.

 
Example 7: Changing the contents of TBufC using Des()

Working with Heap Descriptor HBufC

HBufC is the descriptor of choice when we don't know the size of data that we want to have in the descriptor. Here 'C' stands for constant that means the data is constant but it can also be changed in two ways as it was changed in the case of TBufC<n>. First using the assignment operator and another by using the Modifiable pointer descriptor i.e.TPtr using Des() member function. There are two things to remember while using the HBufC:
  if you need to pass and HBufC to a function that takes TDesC & as parameter, you need to simply dereference the HBufC pointer.
  the Size of Heap Descriptor buffer can be changed using ReAlloc function as oppose to TBufC.

 
Example 8: Usage of HBufC

Usage of TPtr

Ahaa, we are using it in case of TBufC and HBufC, so we know most of it. So let's remember how we can create TPtr.
  Another TPtr.
  From TBufC, HBufC using Des() member function.
  From an explicit Pointer into the memory and specifying the max length.
  From and explicit Pointer into the memory and specifying the data as well as the maximum length.

 
Example 9: Usage of TPtr

Usage of TBuf<n>

In this the data doesn't remains constant. The operations, Instantiation and assignment will be similar to that of the TBufC<n> along with the modification functions that can be applied into it as it was applied in the case of TPtr, like Copy, Delete, assignments etc. I hope I don't need to give some examples for this section.