|
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 task |
|
11 PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd"> |
|
12 <task id="GUID-7984F8F7-DC7B-56E0-A5DA-071A3D87714A" xml:lang="en"><title>LString |
|
13 Tutorial</title><abstract><p>LStrings can be used as class member variables, declared in the |
|
14 class declaration and instantiated in ConstructL(), in the constructor or |
|
15 in the constructor initialisation list. </p></abstract><prolog><metadata><keywords/></metadata></prolog><taskbody> |
|
16 <prereq><p><b>Required background</b></p><p>Before beginning you must know |
|
17 the following: </p> <ul> |
|
18 <li id="GUID-F16B6935-EAF1-5EF1-A69E-4D0D5F48EF95"><p> <xref href="GUID-49D4E917-57EA-39AE-8941-144AA8AC2584.dita"><apiname>TDes </apiname></xref> - |
|
19 Build independent modifiable descriptor. </p> </li> |
|
20 <li id="GUID-FD3CD5F7-E991-5003-B595-15139EE34880"><p> <xref href="GUID-52D07F46-2162-380C-A775-C3BB335C42F5.dita"><apiname>TDesC </apiname></xref> - |
|
21 Build independent non-modifiable descriptor. </p> </li> |
|
22 <li id="GUID-0CD1486E-0B54-5877-91D8-7D5C094B90FD"><p> <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> - |
|
23 This class provides a buffer that contains, accesses and manipulates TUint16 |
|
24 data. The buffer itself is on the heap, and is managed by the class. </p> </li> |
|
25 </ul> </prereq> |
|
26 <context><p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita"><apiname>LString</apiname></xref> is a convenient, general-purpose string |
|
27 class derived from RBuf. LString adds automatic cleanup and on-demand buffer |
|
28 resize facilities. Like an RBuf, an LString can be passed to any function |
|
29 that is prototyped to take a <xref href="GUID-49D4E917-57EA-39AE-8941-144AA8AC2584.dita"><apiname>TDes</apiname></xref> or a <xref href="GUID-52D07F46-2162-380C-A775-C3BB335C42F5.dita"><apiname>TDesC</apiname></xref> reference. |
|
30 Again like an <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref>, an LString maintains its string data |
|
31 in a heap buffer. </p> </context> |
|
32 <steps-unordered> |
|
33 <step id="GUID-3B84AF07-5356-4BFA-91D2-B8FE64121852"><cmd><b>Declaring an LString</b></cmd> |
|
34 <info><p>LStrings can also be used as class member variables, declared in |
|
35 the class declaration and instantiated in <xref href="GUID-C8E0575D-5A7F-3D00-9BE5-AD8D6DBCF2F7.dita"><apiname>ConstructL()</apiname></xref>, |
|
36 in the constructor or in the constructor initialisation list. </p> <p>LString |
|
37 provides a variety of construction options as show in code snippet below: </p> <codeblock id="GUID-760C7BA0-DDBC-5B8C-AD1C-E0E5E7ECCC1D" xml:space="preserve"> |
|
38 { |
|
39 |
|
40 _LIT(KOne, "One "); |
|
41 _LIT(KTesting, "Testing "); |
|
42 |
|
43 |
|
44 // A default constructed LString starts empty, doesn't |
|
45 // allocate any memory on the heap, and therefore the |
|
46 // following cannot leave |
|
47 LString s; |
|
48 |
|
49 // You can initialize with a MaxLength value |
|
50 LString s(KMaxFileName); // This operation may leave |
|
51 |
|
52 // You can initialize from any descriptor (or literal) and the |
|
53 // string data is copied into the LString |
|
54 LString s(KOne); // From a literal |
|
55 |
|
56 LString half(s.Left(s.Length() / 2)); // Left returns a TPtrC |
|
57 |
|
58 // On the other hand, you can initialize from a returned |
|
59 // HBufC* and the LString automatically takes ownership |
|
60 LString own(AllocateNameL(KTesting)); |
|
61 |
|
62 // LStrings can be allocated on the heap if necessary |
|
63 LString* s = new(ELeave) LString; |
|
64 |
|
65 } |
|
66 </codeblock></info> |
|
67 </step> |
|
68 <step id="GUID-2A0AB10A-433B-46BC-A636-86CC128B6F35"><cmd><b>Managing the size of the LString manually</b></cmd> |
|
69 <info><p>Although <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita"><apiname>LString</apiname></xref> supports automatic resizing, |
|
70 it is also possible, and sometimes necessary to manually change the length |
|
71 of the string. When an LString is passed to a function as a <xref href="GUID-49D4E917-57EA-39AE-8941-144AA8AC2584.dita"><apiname>TDes</apiname></xref> or <xref href="GUID-52D07F46-2162-380C-A775-C3BB335C42F5.dita"><apiname>TDesC</apiname></xref>, |
|
72 it looses its automatic resizing capabilities and therefore care must be taken |
|
73 to ensure sufficient space is allocated before the call is made. </p> <p>Extra |
|
74 space can be allocated to the LString by calling <xref href="GUID-A3EE1898-D58C-3C15-8A98-7BEF85963AEB.dita"><apiname>ReserveFreeCapacityL()</apiname></xref> function |
|
75 and the string can be compressed to the minimum length by calling <xref href="GUID-E016AEA6-D901-3AF4-AE52-CBE4308E962C.dita"><apiname>Compress()</apiname></xref> function. |
|
76 An example code snippet is shown below: </p> <codeblock id="GUID-DE899D49-DC9D-53DE-8E7B-B0F19EAF4D8A" xml:space="preserve"> |
|
77 _LIT(KOne, "One "); |
|
78 |
|
79 { |
|
80 LString s(KOne); |
|
81 s.ReserveFreeCapacityL(4); |
|
82 test(s.Length() == 4); |
|
83 test(s.MaxLength() >= 8); |
|
84 s.Compress(); |
|
85 test(s.MaxLength() >= 4); //note indefinite test |
|
86 s.Reset(); |
|
87 test(s.Length() == 0); |
|
88 test(s.MaxLength() == 0); |
|
89 } |
|
90 </codeblock></info> |
|
91 </step> |
|
92 <step id="GUID-5FD35D1B-B252-4266-BCC0-7FC00ED6BF93"><cmd><b>Passing an LString to a function expecting a TDes or TDesC</b></cmd> |
|
93 <info><p> <xref href="GUID-2C3DFAFD-A2DD-3E44-BB1A-580E60EDD8BC.dita"><apiname>LString</apiname></xref>, derived from <xref href="GUID-BFBC574B-EFF6-37A4-9189-B71DA1505BC8.dita"><apiname>RBuf</apiname></xref> can |
|
94 be passed directly to any method accepting a <xref href="GUID-49D4E917-57EA-39AE-8941-144AA8AC2584.dita"><apiname>TDes</apiname></xref> or <xref href="GUID-52D07F46-2162-380C-A775-C3BB335C42F5.dita"><apiname>TDesC</apiname></xref> parameter. |
|
95 Be aware though that once passed as a TDes, LString loses its automatic resizing |
|
96 capability. Care must be taken to ensure that sufficient capacity is reserved |
|
97 by calling <xref href="GUID-A3EE1898-D58C-3C15-8A98-7BEF85963AEB.dita"><apiname>ReserveFreeCapacityL()</apiname></xref> function or <xref href="GUID-B7878C32-D093-3B15-A5B6-E91DA3A0961E.dita"><apiname>SetMaxLengthL() </apiname></xref> function |
|
98 before passing the LString as a TDes. When passed to a function as a TDes |
|
99 a USER 11 panic will be raised if the string is modified and the resulting |
|
100 length of this descriptor is greater than its maximum length. </p> <p>An example |
|
101 code snippet is shown below: </p> <codeblock id="GUID-2BDE3A6B-E974-5E30-AB1A-D670C64AD2F1" xml:space="preserve"> |
|
102 void GetCurrentPath(TDes& aDes) |
|
103 { |
|
104 aDes = KPath; |
|
105 } |
|
106 . . . |
|
107 { |
|
108 LString s; |
|
109 test(s.MaxLength() == 0); |
|
110 s.SetMaxLengthL(KMaxFileName); |
|
111 GetCurrentPath(s); |
|
112 } |
|
113 </codeblock></info> |
|
114 </step> |
|
115 </steps-unordered> |
|
116 </taskbody><related-links> |
|
117 <link href="GUID-B1D5B680-00E3-5702-985A-94256180E2D8.dita"><linktext>Automatic |
|
118 Resource Management</linktext></link> |
|
119 <link href="GUID-69D916D3-ED05-58DA-BA42-CE4D7E4F6482.dita"><linktext>Automatic |
|
120 Resource Management Class Templates Tutorial</linktext></link> |
|
121 <link href="GUID-B419D99E-8312-5336-9693-3ED8DFCD0559.dita"><linktext>Automatic |
|
122 Resource Management Tutorial</linktext></link> |
|
123 </related-links></task> |