|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-4F2F254A-1A81-507A-B364-BE4088D3B3AE" xml:lang="en"><title>How to |
|
13 use literal descriptors</title><shortdesc>Explains how to generate constant literal descriptors.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>Generate a constant literal as follows:</p> |
|
15 <codeblock id="GUID-C3147B10-3247-5EC8-8ED9-A9574EEE4682" xml:space="preserve">_LIT(name, string);</codeblock> |
|
16 <p>where <codeph>name</codeph> is a C++ variable name and <codeph>string</codeph> is |
|
17 the literal text enclosed in a pair of double quotes. </p> |
|
18 <p>All the code fragments use the build independent form but they are equally |
|
19 valid if replaced by the explicit 16 bit variant or the explicit 8 bit variant.</p> |
|
20 <p>As <codeph>name</codeph> represents a constant variable, it is conventional |
|
21 for the variable name to start with a capital <codeph>K</codeph>, for example:</p> |
|
22 <codeblock id="GUID-9CA8C2BA-403B-5E43-A205-0C5690872988" xml:space="preserve">_LIT(KTxtMatchString,"Hello");</codeblock> |
|
23 <p>This generates the constant literal descriptor:</p> |
|
24 <codeblock id="GUID-B40B7B03-CD17-509B-86A2-701D3A902A9A" xml:space="preserve">const static TLitC<5> KTxtMatchString;</codeblock> |
|
25 <p>and this is initialised to contain the string <codeph>Hello</codeph>. Developers |
|
26 never need to code a <codeph>TLitC</codeph> class explicitly; it is always |
|
27 be constructed through the macro.</p> |
|
28 <p>This constant literal descriptor can be passed directly to functions which |
|
29 are prototyped to take a <codeph>const TDesC&</codeph> type:</p> |
|
30 <codeblock id="GUID-CEAF3352-ED10-5E05-9571-F032375FFEE6" xml:space="preserve">TBufC<32> x; |
|
31 ... |
|
32 x.Match(KTxtMatchString); |
|
33 ...</codeblock> |
|
34 <p>The literal descriptor classes: <codeph>TLitC16</codeph>, <codeph>TLitC8</codeph>, <codeph>TLitC16</codeph>, |
|
35 also provide a conversion operator so that they can be passed to functions |
|
36 which take a <codeph>const TRefByValue<const TDesC></codeph> type. |
|
37 This means that they can be passed to functions such as <codeph>TDes::Format()</codeph>:</p> |
|
38 <codeblock id="GUID-0D9639D7-B7EE-50E1-B21A-09D8C0D0FF0A" xml:space="preserve">_LIT(KFormat1,"Length is %d"); |
|
39 ... |
|
40 TBuf<256> x; |
|
41 ... |
|
42 x.Format(KFormat1,8); |
|
43 ...</codeblock> |
|
44 <p>The <codeph>&</codeph> and the <codeph>()</codeph> operators acting |
|
45 on a constant literal return a <codeph>const TDesC*</codeph> and a <codeph>const |
|
46 TDesC&</codeph> type respectively:</p> |
|
47 <codeblock id="GUID-4DA3E378-B0EA-5336-A921-282C632795CC" xml:space="preserve">... |
|
48 _LIT(KTxtMatchString,"Hello"); |
|
49 _LIT(KFormat2,"Text is %S"); |
|
50 ...</codeblock> |
|
51 <codeblock id="GUID-B83E52DD-2638-57EE-BA80-B9377C40404A" xml:space="preserve">TInt length; |
|
52 length = KTxtMatchString().Length(); |
|
53 ... |
|
54 TBuf<256> x; |
|
55 x.Format(KFormat2,&KTxtMatchString); |
|
56 ...</codeblock> |
|
57 </conbody></concept> |