String and Descriptors

The choice of Symbian not to use common types and functions for handling strings and binary buffer may look quite surprising for many developers new to this platform. And probably more than one developer has spent a couple of hours wondering about the respective merits of Tbuf, TbufC, HbufC,...

The main characteristics of Symbian descriptors are:
  strings and binary data are threated the same way
  data can reside in any memory location, either ROM or RAM, on the stack or on the heap
  a descriptor object maintains pointer and length information to describe its data. Some descriptors also include a maximum length

The following diagram shows the descriptor classes hierarchy:

All descriptors inherits from the abstract class TDesC. They come in three types:
  Buffer descriptors - where the data is part of the descriptor object and the descriptor object lives on the program stack: TBufand TBufC,
  Heap descriptors - where the data is part of the descriptor object and the descriptor object lives on the heap: HBufC,
  Pointer descriptors - where the descriptor object is separate from the data it represents: TPtr and TPtrC.

An analogy with classical C/C++ gives:
  TPtrC should be used where const char * used to
  TBufCwhere char [] used to.

The other classes have no equivalent.

Here is how data are organized within each class:

TDes and TDesC are abstract classes so you cannot instantiate them. Their main use is in as argument of function manipulating strings and binary data. In such function, you will use:
  const TDesC& for read-only string or data
  TDes& for passing string or data you want to modify.

All the descriptors can have some width specifier: TDes8, TDes16, TDesC8, TDesC16, TBuf8, TBuf16,... 8 specifies that the descriptor handle 8 bits data, and 16 stands for 16 bits. Generally, you will use the neutral form (TDes, TDesC,...) for text data and the 8 bits version (TDesc8,...) for binary content.

Litterals

Strings constant are often defined using the _L() or _LIT() macros.

_L() produces a TPtrC from a literal value. It is typically used to pass a string to a function:

NEikonEnvironment::MessageBox(_L("Error: init file not found!"));

_LIT() generates named constant that can be reused across your application:

_LIT(KMyFile,"c:\\System\\Apps\\MyApp\\MyFile.jpg");

The result of the _LIT() macro (KmyFile on the example above) is a literal descriptor TLitC which can be used wherever a TDesC& could.

Usage

The most commonly used function are defined in TDesC. They are:
  Ptr() to get a pointer on the descriptor data
  Length() to get the number of characters in the descriptor data.
  Size() to get the number of bytes in the descriptor data.
  Compare() or operators ==, !=, >= and <= for descriptor data comparison
  the operator [] can be used - as in C/C++ - to get a single char from a descriptor string

Several functions pictured above comes in several flavors:
  Append() and Num() have several variants that cannot been described here but are well described in the Symbian Developer Library.
  Compare()has variants named CompareC() and CompareF(). So do Copy(), Find(), Locate(), and Match() : all of these have a C and/or F variant. C stands for Collatedand F for Folded.

Collating and Folding

Folding is a relatively simple way of normalizing text for comparison by removing case distinctions, converting accented characters to characters without accents etc. Folding is typically used for tolerant comparisons

Collation is a much better and more powerful way to compare strings and produces a dictionary-like ('lexicographic') ordering. For languages using the Latin script, for example, collation is about deciding whether to ignore punctuation, whether to fold upper and lower case, how to treat accents, and so on. In a given locale there is usually a standard set of collation rules that can be used.