How to use literal descriptors

Explains how to generate constant literal descriptors.

Generate a constant literal as follows:

_LIT(name, string);

where name is a C++ variable name and string is the literal text enclosed in a pair of double quotes.

All the code fragments use the build independent form but they are equally valid if replaced by the explicit 16 bit variant or the explicit 8 bit variant.

As name represents a constant variable, it is conventional for the variable name to start with a capital K, for example:

_LIT(KTxtMatchString,"Hello");

This generates the constant literal descriptor:

const static TLitC<5> KTxtMatchString;

and this is initialised to contain the string Hello. Developers never need to code a TLitC class explicitly; it is always be constructed through the macro.

This constant literal descriptor can be passed directly to functions which are prototyped to take a const TDesC& type:

TBufC<32> x;
...
x.Match(KTxtMatchString);
...

The literal descriptor classes: TLitC16, TLitC8, TLitC16, also provide a conversion operator so that they can be passed to functions which take a const TRefByValue<const TDesC> type. This means that they can be passed to functions such as TDes::Format():

_LIT(KFormat1,"Length is %d");
...
TBuf<256> x;
...
x.Format(KFormat1,8);
...

The & and the () operators acting on a constant literal return a const TDesC* and a const TDesC& type respectively:

...
_LIT(KTxtMatchString,"Hello");
_LIT(KFormat2,"Text is %S");
...

TInt length;
length = KTxtMatchString().Length();
...
TBuf<256> x;
x.Format(KFormat2,&KTxtMatchString);
...