EPOC   SDK Home Glossary Indexes Previous Next Up

About literal descriptors


Contents


Overview

Section Contents


General

EPOC Release 5 provides a family of macros, _LIT and supporting templated classes, TLitC<TInt> which allow you to create constant literal descriptors.

They satisfy a requirement for creating descriptors containing literal text which can be placed by the compiler into read-only memory; such literal descriptors eliminate the need for a temporary TPtrC to be constructed.

Avoiding the use of a temporary TPtrC, makes your code more efficient by reducing program stack and instruction cycles.

The new macros are intended to replace the old literal macro: _L. While _L is retained by EPOC for compatibility purposes, all new applications and code should use the new macros and classes.

EPOC Release 5 offers three macros:


The literal descriptor classes

Literal descriptors are the TLitC<TInt> family of templated classes and are constructed using the _LIT family of macros.

The literal descriptors are not true descriptors, i.e. they are not derived from TDesC; however, they have conversion operators so that they can be passed to any function which takes a const TDesC& type.

There are three templated classes in the family:

The TLitC8<TInt> variant defines an explicit 8 bit constant literal; this is suitable when non-Unicode literal text is required regardless of the build. A const static instance of this class is constructed by the _LIT8 macro.

The TLitC16<TInt> variant defines an explicit 16 bit constant literal; this is suitable when Unicode literal text is required regardless of the build. A const static instance of this class is constructed by the _LIT16 macro.

The TLitC<TInt> variant defines either an 8 bit constant literal (for non-Unicode text) or a 16 bit constant literal (for Unicode text) depending on the build; i.e. building an application for Unicode generates a 16 bit variant while building the application for non-Unicode generates an 8 bit variant. A const static instance of this class is constructed by the _LIT macro.


Using literal descriptors

Generate a constant literal by coding:

    _LIT(name, string);

where name is a C++ variable name and string is the literal text enclosed in a pair of double quotes. 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 Hello. Developers never need to code a TLItC class explicitly; it can always be constructed from the macro.

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

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

The TLitC<TInt> family of classes also provides 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(); for example:

    _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; for example:

    ...
    _LIT(KTxtMatchString,"Hello");
    _LIT(KFormat2,"Text is %S");
    ...
    TInt length;
    length = KTxtMatchString().Length();
    ...
    TBuf<256> x;
    x.Format(KFormat2,&KTxtMatchString);
    ...

Literals can be defined at file-scope (including header files), in which case they are visible to any code that follows. They can also be declared local to the function which uses them. However, note the following:

Thus, if the descriptor is short or used only in an inline function, it is better to define it at file-scope with a suitably distinct name.


The NULL constant literals

EPOC Release 5 provides a pre-defined constant literal descriptor for NULL text. There are three variants with names: KNullDesC, KNullDesC8 and KNullDesC16, defined in e32std.h as:

EPOC       SDK Home Glossary Indexes Previous Next Up