|
1 // Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 #ifndef ESTRING_H |
|
17 #define ESTRING_H |
|
18 |
|
19 #include <e32std.h> |
|
20 |
|
21 // this macro is defined only if the target is WINSCW and wchar_t is ON |
|
22 // (i.e OPTION CW -wchar_t on) |
|
23 // and if the target is any thing other than WINSCW |
|
24 // it is being assumed that wchar_t is ON(OPTION CW -wchar_t on by |
|
25 // default or other wise) |
|
26 #define NATIVE_WCHAR // most platforms do wchar_t properly |
|
27 #if defined __cplusplus && defined __WINSCW__ |
|
28 #if !__option(wchar_type) // without the wchar_type option |
|
29 typedef unsigned short wchar_t; // needs a typedef |
|
30 #undef NATIVE_WCHAR // which is not native |
|
31 #endif |
|
32 #endif |
|
33 |
|
34 // Since the LStrings can leave in their constructors, we have to make |
|
35 // sure to avoid the operator new/delete ELeave mismatch problem that |
|
36 // can result in the top level LString object heap being |
|
37 // leaked. These operator delete overloads match the global operator |
|
38 // new overloads applicable to the LString classes (which are |
|
39 // non-CBase derived). |
|
40 // |
|
41 // Note that when allocating a native C++ array of LStrings, only the |
|
42 // default constructor is invoked which cannot leave. So there are no |
|
43 // issues related to the array case. |
|
44 |
|
45 #define LSTRING_CONSTRUCTORS_MAY_LEAVE \ |
|
46 static void operator delete(TAny* aPtr) __NO_THROW \ |
|
47 { \ |
|
48 return ::operator delete(aPtr); \ |
|
49 } \ |
|
50 \ |
|
51 static void operator delete(TAny* aPtr, TLeave) __NO_THROW \ |
|
52 { \ |
|
53 return ::operator delete(aPtr); \ |
|
54 } \ |
|
55 \ |
|
56 static void operator delete(TAny*, TAny*) __NO_THROW \ |
|
57 { \ |
|
58 } |
|
59 |
|
60 /** |
|
61 @file |
|
62 |
|
63 A self-managing descriptor class |
|
64 |
|
65 @publishedAll |
|
66 @released |
|
67 */ |
|
68 |
|
69 /** |
|
70 @class LString8 |
|
71 |
|
72 LString8 is a convenient, general-purpose 8 bit string class derived |
|
73 from RBuf8. LString8 adds automatic cleanup and on-demand buffer |
|
74 resize facilities. |
|
75 |
|
76 @par L-Classes |
|
77 |
|
78 Note: The L prefix denotes that construction, copying, passing and |
|
79 returning by value, assignment, and manipulation via operators should |
|
80 all be considered potentially leaving operations unless otherwise |
|
81 explicitly documented. Code that uses LString8 should be written |
|
82 accordingly, in leave-safe style. |
|
83 |
|
84 @par Descriptor Relationships |
|
85 |
|
86 Like an RBuf8, an LString8 can be passed to any function that is |
|
87 prototyped to take a TDes8 or a TDesC8 reference. Again like an |
|
88 RBuf8, an LString8 maintains its string data in a heap buffer. |
|
89 |
|
90 @par Value-Type Behaviour |
|
91 |
|
92 Unlike RBuf8, an LString8 may be used much like a simple T class; |
|
93 LString8 typed variables will automatically clean up after themselves |
|
94 when they go out of scope, and LString8 typed fields will similarly |
|
95 automatically release all owned resources when their containing object |
|
96 is destroyed. |
|
97 |
|
98 For example, where: |
|
99 |
|
100 @code |
|
101 RBuf8 buf; |
|
102 buf.CleanupClosePushL(); |
|
103 ... |
|
104 CleanupStack::PopAndDestroy(); |
|
105 @endcode |
|
106 |
|
107 would be required, with LString8: |
|
108 |
|
109 @code |
|
110 LString8 buf; |
|
111 ... |
|
112 @endcode |
|
113 |
|
114 will suffice. Pushing an LString8 onto the cleanup stack is not |
|
115 necessary or recommended, but the effects of doing so are |
|
116 benign. LString8 instances can also be passed and returned by value, |
|
117 but note that doing so may trigger implicit heap allocation and cause |
|
118 a leave with KErrNoMemory. |
|
119 |
|
120 @code |
|
121 void TakeString(LString8 aString) |
|
122 { |
|
123 // ... |
|
124 } |
|
125 |
|
126 LString8 ReturnString(LString8 aString) |
|
127 { |
|
128 TakeString(aString); // Statement may leave with KErrNoMemory |
|
129 return aString; // Statement may leave with KErrNoMemory |
|
130 } |
|
131 @endcode |
|
132 |
|
133 As with other descriptors, passing by reference when possible is more |
|
134 efficient. |
|
135 |
|
136 @par On-Demand Growth |
|
137 |
|
138 In addition to the value-type semantics described above, LString8 |
|
139 also supports automatic in-place resizing. All standard descriptor |
|
140 methods are available, but for any non-leaving descriptor method that |
|
141 may panic due to buffer overflow, LString8 adds a corresponding |
|
142 leaving method that automatically expands the underlying buffer |
|
143 on-demand. For example, Append() will panic if the new data overflows |
|
144 available buffer space, while AppendL() will attempt to realloc the |
|
145 buffer as necessary. The new leaving variants may therefore leave with |
|
146 KErrNoMemory, may invalidate any existing raw pointers into the data |
|
147 buffer (e.g. those previously returned by Ptr()), and may change the |
|
148 value returned by MaxLength(). |
|
149 |
|
150 @code |
|
151 LString8 message; // Zero length |
|
152 message.FormatL(_L("This is message %n from %S"), n, &s); // FormatL automatically grows the buffer |
|
153 User::InfoPrint(message); |
|
154 @endcode |
|
155 |
|
156 It is important to note that LString8 only supports automatic growth |
|
157 when being manipulated directly as an LString8. When an LString8 is |
|
158 passed to a function accepting a TDes8, that function will operate on |
|
159 it as if it is a fixed-max-length descriptor. In that case, adequate |
|
160 capacity must be reserved within the LString8 prior to calling the |
|
161 function. This can either be achieved using the appropriate constructor or ReserveFreeCapacityL(). |
|
162 |
|
163 @code |
|
164 extern void GetLastQuery(TDes8& aQuery); |
|
165 extern void GetLastAuxQuery(TDes8& aQuery); |
|
166 |
|
167 LString8 query(KMaxQuerySize); // Guarantees query.MaxLength() >= KMaxQuerySize |
|
168 GetLastQuery(query); |
|
169 |
|
170 // ... |
|
171 |
|
172 previousQueryMaxLength = query.MaxLength(); |
|
173 |
|
174 query.ReserveFreeCapacityL(KExtraRequiredSize); // Guarantees query.MaxLength() >= KExtraRequiredSize + previousQueryMaxLength; |
|
175 GetLastAuxQuery(query); |
|
176 |
|
177 @endcode |
|
178 |
|
179 @par Relationship with TDes and RBuf |
|
180 |
|
181 LString8 derives from RBuf8 in order to achieve maximum |
|
182 interoperability with existing descriptor-accepting APIs. This |
|
183 derivation forces some unusual API compromises, however, due to the |
|
184 unique characteristics of LString8 compared to other descriptors. |
|
185 |
|
186 Some of the mutating methods on the base classes, TDes8 and RBuf8, |
|
187 panic when called with insufficient buffer space. Sufficient space is |
|
188 a precondition of these base classes which LString8 relaxes with |
|
189 its capability to start with zero length. LString8 defines new |
|
190 leaving variants of these methods with auto-growth behaviour |
|
191 (e.g. AppendL), but at the same time inherits the original methods |
|
192 (e.g. Append). This makes it too easy for developers to call the |
|
193 wrong method inadvertently. In order to address this, the original |
|
194 non-leaving methods have been made private in LString8. Developers |
|
195 should use the leaving LString8 versions. |
|
196 |
|
197 Note that, if required for any reason, the non-leaving method variants |
|
198 may be accessed by explicitly qualifying the method name to the |
|
199 appropriate parent type. For example: aString.TDes::Append(...). When |
|
200 working with an LString8 but doing so via a TDes& typed variable, all |
|
201 TDes8 APIs are directly available. |
|
202 |
|
203 Hiding these methods does not remove the problem entirely. The same |
|
204 problem can happen if an LString object of insufficient size in passed |
|
205 into a any API accepting a TDes. The advice is that developers always |
|
206 ensure there is sufficient space before passing LString as a TDes. |
|
207 |
|
208 @par Performance Concerns |
|
209 |
|
210 While being simpler to use than existing descriptors in many cases, |
|
211 LString8's use of heap allocation and its resizing variant methods |
|
212 clearly come with associated costs. Their use in performance-critical |
|
213 code should be carefully considered. On the other hand, LString8's |
|
214 small stack footprint and ability to better-handle inputs of |
|
215 unpredictable size may make them a better choice when the alternative |
|
216 is a large, fixed-max-size TBuf or HBufC. |
|
217 |
|
218 @par Buffer Ownership |
|
219 |
|
220 Typically an LString8 will automatically allocate its own buffer, but |
|
221 like RBuf8 it can also take ownership of a pre-existing raw memory |
|
222 buffer or heap descriptor. |
|
223 |
|
224 The class is intended for instantiation. |
|
225 |
|
226 @see RBuf8 |
|
227 @see TBuf8 |
|
228 @see TPtr8 |
|
229 @see HBufC8 |
|
230 @see TDesC8 |
|
231 @see TDes8 |
|
232 @see LString |
|
233 |
|
234 */ |
|
235 class LString8 : public RBuf8 |
|
236 { |
|
237 public: |
|
238 /* |
|
239 * We add leaving (auto-resizing) variants of the standard TDes |
|
240 * methods where appropriate, and enhance the behaviour of the |
|
241 * corresponding operators to match |
|
242 */ |
|
243 |
|
244 LSTRING_CONSTRUCTORS_MAY_LEAVE |
|
245 |
|
246 IMPORT_C LString8(); |
|
247 IMPORT_C ~LString8(); |
|
248 |
|
249 // Construct with initial capacity |
|
250 IMPORT_C explicit LString8(TInt aInitialCapacity); |
|
251 |
|
252 // Construct by data copying |
|
253 IMPORT_C LString8(const TDesC8& aDes); |
|
254 IMPORT_C LString8(const TUint8* aZeroTerminatedString); |
|
255 IMPORT_C LString8(const LString8& aDes); |
|
256 |
|
257 // Construction thru transfer of ownership |
|
258 IMPORT_C explicit LString8(HBufC8* aHBuf); |
|
259 IMPORT_C explicit LString8(TUint8 *aHeapCell,TInt aMaxLength); |
|
260 IMPORT_C explicit LString8(TUint8 *aHeapCell,TInt aLength,TInt aMaxLength); |
|
261 |
|
262 // Assignment thru payload copying |
|
263 IMPORT_C LString8& operator=(const TDesC8& aDes); |
|
264 IMPORT_C LString8& operator=(const LString8& aDes); |
|
265 IMPORT_C LString8& operator=(const TUint8* aZeroTerminatedString); |
|
266 |
|
267 // Assignment by transfer of payload to this object; |
|
268 // supplied object is destroyed or zeroed. |
|
269 IMPORT_C LString8& operator=(HBufC8* aHBuf); |
|
270 |
|
271 // Assign by transfer of payload ownership to this object; |
|
272 // supplied object is destroyed or zeroed. |
|
273 IMPORT_C void Assign(const LString8& aString); |
|
274 IMPORT_C void Assign(const RBuf8& aRBuf); |
|
275 IMPORT_C void Assign(HBufC8* aHBuf); |
|
276 IMPORT_C void Assign(TUint8 *aHeapCell,TInt aMaxLength); |
|
277 IMPORT_C void Assign(TUint8 *aHeapCell,TInt aLength,TInt aMaxLength); |
|
278 |
|
279 IMPORT_C void CreateL(RReadStream& aStream,TInt aMaxLength); |
|
280 |
|
281 IMPORT_C LString8& operator+=(TChar aChar); |
|
282 IMPORT_C LString8& operator+=(const TDesC8 &aDes); |
|
283 |
|
284 IMPORT_C void CopyL(const TDesC8 &aDes); |
|
285 IMPORT_C void CopyL(const TDesC16 &aDes); |
|
286 IMPORT_C void CopyL(const TUint8 *aZeroTerminatedString); |
|
287 IMPORT_C void CopyL(const TUint8 *aBuf,TInt aLength); |
|
288 |
|
289 IMPORT_C void SetLengthL(TInt aLength); |
|
290 IMPORT_C void SetMaxLengthL(TInt aMaxLength); |
|
291 IMPORT_C void Compress(); // deprecated; to be removed |
|
292 IMPORT_C void ReserveFreeCapacityL(TInt aExtraSpaceLength); |
|
293 IMPORT_C void Reset(); |
|
294 |
|
295 IMPORT_C void AppendL(TChar aChar); |
|
296 IMPORT_C void AppendL(const TDesC8 &aDes); |
|
297 IMPORT_C void AppendL(const TUint8 *aBuf,TInt aLength); |
|
298 |
|
299 IMPORT_C void FillL(TChar aChar,TInt aLength); |
|
300 IMPORT_C void FillZL(TInt aLength); |
|
301 |
|
302 IMPORT_C void NumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth); |
|
303 IMPORT_C void AppendNumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth); |
|
304 IMPORT_C const TUint8 *PtrZL(); |
|
305 IMPORT_C void CopyFL(const TDesC8 &aDes); |
|
306 IMPORT_C void CopyCL(const TDesC8 &aDes); |
|
307 IMPORT_C void CopyLCL(const TDesC8 &aDes); |
|
308 IMPORT_C void CopyUCL(const TDesC8 &aDes); |
|
309 IMPORT_C void CopyCPL(const TDesC8 &aDes); |
|
310 IMPORT_C void AppendFillL(TChar aChar,TInt aLength); |
|
311 IMPORT_C void ZeroTerminateL(); |
|
312 IMPORT_C void SwapL(TDes8 &aDes); |
|
313 IMPORT_C void SwapL(LString8 &aDes); // Added overload |
|
314 IMPORT_C void InsertL(TInt aPos,const TDesC8 &aDes); |
|
315 IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const TDesC8 &aDes); |
|
316 IMPORT_C void JustifyL(const TDesC8 &aDes,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
317 IMPORT_C void NumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth); |
|
318 IMPORT_C void NumUCL(TUint64 aVal, TRadix aRadix=EDecimal); |
|
319 IMPORT_C TInt NumL(TReal aVal,const TRealFormat &aFormat) __SOFTFP; |
|
320 IMPORT_C void NumL(TInt64 aVal); |
|
321 IMPORT_C void NumL(TUint64 aVal, TRadix aRadix); |
|
322 IMPORT_C void FormatL(TRefByValue<const TDesC8> aFmt,...); |
|
323 IMPORT_C void FormatListL(const TDesC8 &aFmt,VA_LIST aList); |
|
324 IMPORT_C void AppendJustifyL(const TDesC8 &Des,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
325 IMPORT_C void AppendJustifyL(const TDesC8 &Des,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
326 IMPORT_C void AppendJustifyL(const TUint8 *aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
327 IMPORT_C void AppendJustifyL(const TUint8 *aString,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
328 IMPORT_C void AppendNumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth); |
|
329 IMPORT_C void AppendNumUCL(TUint64 aVal, TRadix aRadix=EDecimal); |
|
330 IMPORT_C TInt AppendNumL(TReal aVal,const TRealFormat &aFormat) __SOFTFP; |
|
331 IMPORT_C void AppendNumL(TInt64 aVal); |
|
332 IMPORT_C void AppendNumL(TUint64 aVal, TRadix aRadix); |
|
333 IMPORT_C void AppendFormatL(TRefByValue<const TDesC8> aFmt,...); |
|
334 IMPORT_C void AppendFormatListL(const TDesC8 &aFmt,VA_LIST aList); |
|
335 |
|
336 using RBuf8::operator==; |
|
337 IMPORT_C TBool operator==( const TUint8* aZeroTerminatedString) const; |
|
338 using RBuf8::operator<; |
|
339 IMPORT_C TBool operator<( const TUint8* aZeroTerminatedString) const; |
|
340 using RBuf8::operator<=; |
|
341 IMPORT_C TBool operator<=( const TUint8* aZeroTerminatedString) const; |
|
342 using RBuf8::operator>; |
|
343 IMPORT_C TBool operator>( const TUint8* aZeroTerminatedString) const; |
|
344 using RBuf8::operator>=; |
|
345 IMPORT_C TBool operator>=( const TUint8* aZeroTerminatedString) const; |
|
346 using RBuf8::operator!=; |
|
347 IMPORT_C TBool operator!=( const TUint8* aZeroTerminatedString) const; |
|
348 using RBuf8::Compare; |
|
349 IMPORT_C TInt Compare(const TUint8* aZeroTerminatedString) const; |
|
350 using RBuf8::CompareF; |
|
351 IMPORT_C TInt CompareF(const TUint8* aZeroTerminatedString) const; |
|
352 using RBuf8::Match; |
|
353 IMPORT_C TInt Match(const TUint8* aZeroTerminatedString) const; |
|
354 using RBuf8::MatchF; |
|
355 IMPORT_C TInt MatchF(const TUint8* aZeroTerminatedString) const; |
|
356 using RBuf8::Find; |
|
357 IMPORT_C TInt Find(const TUint8* aZeroTerminatedString) const; |
|
358 using RBuf8::FindF; |
|
359 IMPORT_C TInt FindF(const TUint8* aZeroTerminatedString) const; |
|
360 |
|
361 IMPORT_C void CopyFL(const TUint8* aZeroTerminatedString); |
|
362 IMPORT_C void CopyLCL(const TUint8* aZeroTerminatedString); |
|
363 IMPORT_C void CopyUCL(const TUint8* aZeroTerminatedString); |
|
364 IMPORT_C void CopyCPL(const TUint8* aZeroTerminatedString); |
|
365 IMPORT_C void InsertL(TInt aPos,const TUint8* aZeroTerminatedString); |
|
366 IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const TUint8* aZeroTerminatedString); |
|
367 IMPORT_C void JustifyL(const TUint8* aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
368 IMPORT_C void AppendL(const TUint8* aZeroTerminatedString); |
|
369 IMPORT_C LString8& operator+=(const TUint8* aZeroTerminatedString); |
|
370 |
|
371 IMPORT_C LString8(const char* aCharStr); |
|
372 |
|
373 IMPORT_C TBool operator==( const char* aCharStr) const; |
|
374 IMPORT_C TBool operator<( const char* aCharStr) const; |
|
375 IMPORT_C TBool operator<=( const char* aCharStr) const; |
|
376 IMPORT_C TBool operator>( const char* aCharStr) const; |
|
377 IMPORT_C TBool operator>=( const char* aCharStr) const; |
|
378 IMPORT_C TBool operator!=( const char* aCharStr) const; |
|
379 IMPORT_C TInt Compare(const char* aCharStr) const; |
|
380 IMPORT_C TInt CompareF(const char* aCharStr) const; |
|
381 IMPORT_C TInt Match(const char* aCharStr) const; |
|
382 IMPORT_C TInt MatchF(const char* aCharStr) const; |
|
383 IMPORT_C TInt Find(const char* aCharStr) const; |
|
384 IMPORT_C TInt Find(const char* aCharStr,TInt aLenS ) const; |
|
385 IMPORT_C TInt FindF(const char* aCharStr) const; |
|
386 IMPORT_C TInt FindF(const char* aCharStr,TInt aLenS) const; |
|
387 |
|
388 IMPORT_C LString8& operator=(const char* aCharStr); |
|
389 IMPORT_C LString8& operator+=(const char* aCharStr); |
|
390 IMPORT_C void CopyL(const char* aCharStr); |
|
391 IMPORT_C void CopyFL(const char* aCharStr); |
|
392 IMPORT_C void CopyLCL(const char* aCharStr); |
|
393 IMPORT_C void CopyUCL(const char* aCharStr); |
|
394 IMPORT_C void CopyCPL(const char* aCharStr); |
|
395 IMPORT_C void InsertL(TInt aPos,const char* aCharStr); |
|
396 IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const char* aCharStr); |
|
397 IMPORT_C void AppendL(const char* aCharStr, TInt aLength); |
|
398 IMPORT_C void AppendL(const char *aCharStr ); |
|
399 IMPORT_C void JustifyL(const char* aCharStr,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
400 IMPORT_C void AppendJustifyL(const char* aCharStr,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
401 IMPORT_C void AppendJustifyL(const char* aCharStr,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
402 |
|
403 protected: |
|
404 |
|
405 private: |
|
406 /* |
|
407 * capacity management methods |
|
408 */ |
|
409 void ReserveL(TInt aMinRequiredCapacity); |
|
410 void ReserveCapacityGrowExponentialL(TInt aRequiredCapacity); |
|
411 void ReserveCapacityGrowExponentialL(); |
|
412 void ReserveFreeCapacityGrowExponentialL(TInt aRequiredEmptySpace); |
|
413 |
|
414 |
|
415 //---------------------------------------------------------- |
|
416 // These mutable TDes8 methods panic when called with an insufficient |
|
417 // buffer space. |
|
418 // A precondition for TDes8 use is that a sufficient |
|
419 // sufficient buffer is allocated before making calls that write to the |
|
420 // buffer. LString invalidates this precondition. |
|
421 // LString inheriting these TDes methods makes it easy |
|
422 // for developers to call them inadvertently. They have been made |
|
423 // private to ensure the misunderstanding never happens. Developers should |
|
424 // use the leaving (L suffixed) LString equivalents. |
|
425 void SetLength(TInt aLength); |
|
426 void SetMax(); |
|
427 void Copy(const TDesC8 &aDes); |
|
428 void Copy(const TDesC16 &aDes); |
|
429 void Copy(const TUint8 *aBuf,TInt aLength); |
|
430 void Copy(const TUint8 *aString); |
|
431 void Append(TChar aChar); |
|
432 void Append(const TDesC8 &aDes); |
|
433 void Append(const TUint8 *aBuf,TInt aLength); |
|
434 void Fill(TChar aChar,TInt aLength); |
|
435 void FillZ(TInt aLength); |
|
436 void NumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth); |
|
437 void AppendNumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth); |
|
438 const TUint8 *PtrZ(); |
|
439 void CopyF(const TDesC8 &aDes); |
|
440 void CopyC(const TDesC8 &aDes); |
|
441 void CopyLC(const TDesC8 &aDes); |
|
442 void CopyUC(const TDesC8 &aDes); |
|
443 void CopyCP(const TDesC8 &aDes); |
|
444 void AppendFill(TChar aChar,TInt aLength); |
|
445 void ZeroTerminate(); |
|
446 void Swap(TDes8 &aDes); |
|
447 void Insert(TInt aPos,const TDesC8 &aDes); |
|
448 void Replace(TInt aPos,TInt aLength,const TDesC8 &aDes); |
|
449 void Justify(const TDesC8 &aDes,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
450 void NumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth); |
|
451 void NumUC(TUint64 aVal, TRadix aRadix=EDecimal); |
|
452 TInt Num(TReal aVal,const TRealFormat &aFormat) __SOFTFP; |
|
453 void Num(TInt64 aVal); |
|
454 void Num(TUint64 aVal, TRadix aRadix); |
|
455 void Format(TRefByValue<const TDesC8> aFmt,...); |
|
456 void FormatList(const TDesC8 &aFmt,VA_LIST aList); |
|
457 void AppendJustify(const TDesC8 &Des,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
458 void AppendJustify(const TDesC8 &Des,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
459 void AppendJustify(const TUint8 *aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
460 void AppendJustify(const TUint8 *aZeroTerminatedString,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
461 void AppendNumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth); |
|
462 void AppendNumUC(TUint64 aVal, TRadix aRadix=EDecimal); |
|
463 TInt AppendNum(TReal aVal,const TRealFormat &aFormat) __SOFTFP; |
|
464 void AppendNum(TInt64 aVal); |
|
465 void AppendNum(TUint64 aVal, TRadix aRadix); |
|
466 void AppendFormat(TRefByValue<const TDesC8> aFmt,TDes8Overflow *aOverflowHandler,...); |
|
467 void AppendFormat(TRefByValue<const TDesC8> aFmt,...); |
|
468 void AppendFormatList(const TDesC8 &aFmt,VA_LIST aList,TDes8Overflow *aOverflowHandler=NULL); |
|
469 // end of TDes8 methods |
|
470 //--------------------------------------------------- |
|
471 |
|
472 //---------------------------------------------------------- |
|
473 // These mutable RBuf8 methods have been privatised because |
|
474 // they make assumptions which are incompatible with the |
|
475 // general use pattern of LString16. |
|
476 void Swap(RBuf8& aRBuf); |
|
477 TInt Create(TInt aMaxLength); |
|
478 void CreateL(TInt aMaxLength); |
|
479 TInt CreateMax(TInt aMaxLength); |
|
480 void CreateMaxL(TInt aMaxLength); |
|
481 TInt Create(const TDesC8& aDes); |
|
482 void CreateL(const TDesC8& aDes); |
|
483 TInt Create(const TDesC8& aDes,TInt aMaxLength); |
|
484 void CreateL(const TDesC8& aDes,TInt aMaxLength); |
|
485 void Close(); |
|
486 void CleanupClosePushL(); |
|
487 // end of privated RBuf16 methods |
|
488 //--------------------------------------------------- |
|
489 |
|
490 void EnsureCapacityIncrementL(TInt aLengthIncrement); |
|
491 void IncreaseCapacityL(); |
|
492 |
|
493 private: |
|
494 //reserved data member for future-proofing |
|
495 TInt iReserved; |
|
496 }; |
|
497 |
|
498 /** |
|
499 This is the 16-bit version of LString8. All the comments on LString8 apply equally. |
|
500 |
|
501 @see LString8 |
|
502 @see RBuf16 |
|
503 @see TBuf16 |
|
504 @see TPtr16 |
|
505 @see HBufC16 |
|
506 @see TDesC16 |
|
507 @see TDes16 |
|
508 @see LString |
|
509 */ |
|
510 class LString16 : public RBuf16 |
|
511 { |
|
512 public: |
|
513 /* |
|
514 * We add leaving (auto-resizing) variants of the standard TDes |
|
515 * methods where appropriate, and enhance the behaviour of the |
|
516 * corresponding operators to match |
|
517 */ |
|
518 |
|
519 LSTRING_CONSTRUCTORS_MAY_LEAVE |
|
520 |
|
521 IMPORT_C LString16(); |
|
522 IMPORT_C ~LString16(); |
|
523 |
|
524 // Construct with initial capacity |
|
525 IMPORT_C explicit LString16(TInt aInitialCapacity); |
|
526 |
|
527 // Construct by data copying |
|
528 IMPORT_C LString16(const TDesC16& aDes); |
|
529 IMPORT_C LString16(const TUint16* aZeroTerminatedString); |
|
530 IMPORT_C LString16(const LString16& aDes); |
|
531 |
|
532 // Construction thru transfer of ownership |
|
533 IMPORT_C explicit LString16(HBufC16* aHBuf); |
|
534 IMPORT_C explicit LString16(TUint16 *aHeapCell,TInt aMaxLength); |
|
535 IMPORT_C explicit LString16(TUint16 *aHeapCell,TInt aLength,TInt aMaxLength); |
|
536 |
|
537 // Assignment thru payload copying |
|
538 IMPORT_C LString16& operator=(const TDesC16& aDes); |
|
539 IMPORT_C LString16& operator=(const LString16& aDes); |
|
540 IMPORT_C LString16& operator=(const TUint16* aZeroTerminatedString); |
|
541 |
|
542 // Assignment by transfer of payload to this object; |
|
543 // supplied object is destroyed or zeroed. |
|
544 IMPORT_C LString16& operator=(HBufC16* aHBuf); |
|
545 |
|
546 // Assign by transfer of payload ownership to this object; |
|
547 // supplied object is destroyed or zeroed. |
|
548 IMPORT_C void Assign(const LString16& aString); |
|
549 IMPORT_C void Assign(const RBuf16& aRBuf); |
|
550 IMPORT_C void Assign(HBufC16* aHBuf); |
|
551 IMPORT_C void Assign(TUint16 *aHeapCell,TInt aMaxLength); |
|
552 IMPORT_C void Assign(TUint16 *aHeapCell,TInt aLength,TInt aMaxLength); |
|
553 |
|
554 IMPORT_C void CreateL(RReadStream& aStream,TInt aMaxLength); |
|
555 |
|
556 IMPORT_C LString16& operator+=(TChar aChar); |
|
557 IMPORT_C LString16& operator+=(const TDesC16 &aDes); |
|
558 |
|
559 IMPORT_C void CopyL(const TDesC16 &aDes); |
|
560 IMPORT_C void CopyL(const TUint16 *aZeroTerminatedString); |
|
561 IMPORT_C void CopyL(const TDesC8 &aDes); |
|
562 IMPORT_C void CopyL(const TUint16 *aBuf,TInt aLength); |
|
563 |
|
564 IMPORT_C void SetLengthL(TInt aLength); |
|
565 IMPORT_C void SetMaxLengthL(TInt aMaxLength); |
|
566 IMPORT_C void Compress(); // deprecated; to be removed |
|
567 IMPORT_C void ReserveFreeCapacityL(TInt aExtraSpaceLength); |
|
568 IMPORT_C void Reset(); |
|
569 |
|
570 IMPORT_C void AppendL(TChar aChar); |
|
571 IMPORT_C void AppendL(const TDesC16 &aDes); |
|
572 IMPORT_C void AppendL(const TUint16 *aBuf,TInt aLength); |
|
573 |
|
574 IMPORT_C void FillL(TChar aChar,TInt aLength); |
|
575 IMPORT_C void FillZL(TInt aLength); |
|
576 |
|
577 IMPORT_C void NumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth); |
|
578 IMPORT_C void AppendNumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth); |
|
579 IMPORT_C const TUint16 *PtrZL(); |
|
580 IMPORT_C void CopyFL(const TDesC16 &aDes); |
|
581 IMPORT_C void CopyCL(const TDesC16 &aDes); |
|
582 IMPORT_C void CopyLCL(const TDesC16 &aDes); |
|
583 IMPORT_C void CopyUCL(const TDesC16 &aDes); |
|
584 IMPORT_C void CopyCPL(const TDesC16 &aDes); |
|
585 IMPORT_C void AppendFillL(TChar aChar,TInt aLength); |
|
586 IMPORT_C void ZeroTerminateL(); |
|
587 IMPORT_C void SwapL(TDes16 &aDes); |
|
588 IMPORT_C void SwapL(LString16 &aDes); // Added overload |
|
589 IMPORT_C void InsertL(TInt aPos,const TDesC16 &aDes); |
|
590 IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const TDesC16 &aDes); |
|
591 IMPORT_C void JustifyL(const TDesC16 &aDes,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
592 IMPORT_C void NumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth); |
|
593 IMPORT_C void NumUCL(TUint64 aVal, TRadix aRadix=EDecimal); |
|
594 IMPORT_C TInt NumL(TReal aVal,const TRealFormat &aFormat) __SOFTFP; |
|
595 IMPORT_C void NumL(TInt64 aVal); |
|
596 IMPORT_C void NumL(TUint64 aVal, TRadix aRadix); |
|
597 IMPORT_C void FormatL(TRefByValue<const TDesC16> aFmt,...); |
|
598 IMPORT_C void FormatListL(const TDesC16 &aFmt,VA_LIST aList); |
|
599 IMPORT_C void AppendJustifyL(const TDesC16 &Des,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
600 IMPORT_C void AppendJustifyL(const TDesC16 &Des,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
601 IMPORT_C void AppendJustifyL(const TUint16 *aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
602 IMPORT_C void AppendJustifyL(const TUint16 *aString,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
603 IMPORT_C void AppendNumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth); |
|
604 IMPORT_C void AppendNumUCL(TUint64 aVal, TRadix aRadix=EDecimal); |
|
605 IMPORT_C TInt AppendNumL(TReal aVal,const TRealFormat &aFormat) __SOFTFP; |
|
606 IMPORT_C void AppendNumL(TInt64 aVal); |
|
607 IMPORT_C void AppendNumL(TUint64 aVal, TRadix aRadix); |
|
608 IMPORT_C void AppendFormatL(TRefByValue<const TDesC16> aFmt,...); |
|
609 IMPORT_C void AppendFormatListL(const TDesC16 &aFmt,VA_LIST aList); |
|
610 |
|
611 using RBuf16::operator==; |
|
612 IMPORT_C TBool operator==( const TUint16* aZeroTerminatedString) const; |
|
613 using RBuf16::operator<; |
|
614 IMPORT_C TBool operator<( const TUint16* aZeroTerminatedString) const; |
|
615 using RBuf16::operator<=; |
|
616 IMPORT_C TBool operator<=( const TUint16* aZeroTerminatedString) const; |
|
617 using RBuf16::operator>; |
|
618 IMPORT_C TBool operator>( const TUint16* aZeroTerminatedString) const; |
|
619 using RBuf16::operator>=; |
|
620 IMPORT_C TBool operator>=( const TUint16* aZeroTerminatedString) const; |
|
621 using RBuf16::operator!=; |
|
622 IMPORT_C TBool operator!=( const TUint16* aZeroTerminatedString) const; |
|
623 using RBuf16::Compare; |
|
624 IMPORT_C TInt Compare(const TUint16* aZeroTerminatedString) const; |
|
625 using RBuf16::CompareF; |
|
626 IMPORT_C TInt CompareF(const TUint16* aZeroTerminatedString) const; |
|
627 using RBuf16::Match; |
|
628 IMPORT_C TInt Match(const TUint16* aZeroTerminatedString) const; |
|
629 using RBuf16::MatchF; |
|
630 IMPORT_C TInt MatchF(const TUint16* aZeroTerminatedString) const; |
|
631 using RBuf16::Find; |
|
632 IMPORT_C TInt Find(const TUint16* aZeroTerminatedString) const; |
|
633 using RBuf16::FindF; |
|
634 IMPORT_C TInt FindF(const TUint16* aZeroTerminatedString) const; |
|
635 |
|
636 IMPORT_C void CopyFL(const TUint16* aZeroTerminatedString); |
|
637 IMPORT_C void CopyLCL(const TUint16* aZeroTerminatedString); |
|
638 IMPORT_C void CopyUCL(const TUint16* aZeroTerminatedString); |
|
639 IMPORT_C void CopyCPL(const TUint16* aZeroTerminatedString); |
|
640 IMPORT_C void InsertL(TInt aPos,const TUint16* aZeroTerminatedString); |
|
641 IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const TUint16* aZeroTerminatedString); |
|
642 IMPORT_C void JustifyL(const TUint16* aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
643 IMPORT_C void AppendL(const TUint16* aZeroTerminatedString); |
|
644 IMPORT_C LString16& operator+=(const TUint16* aZeroTerminatedString); |
|
645 |
|
646 #ifdef NATIVE_WCHAR |
|
647 IMPORT_C LString16(const wchar_t* aWideCharStr); |
|
648 |
|
649 IMPORT_C TBool operator==( const wchar_t* aWideCharStr) const; |
|
650 IMPORT_C TBool operator<( const wchar_t* aWideCharStr) const; |
|
651 IMPORT_C TBool operator<=( const wchar_t* aWideCharStr) const; |
|
652 IMPORT_C TBool operator>( const wchar_t* aWideCharStr) const; |
|
653 IMPORT_C TBool operator>=( const wchar_t* aWideCharStr) const; |
|
654 IMPORT_C TBool operator!=( const wchar_t* aWideCharStr) const; |
|
655 IMPORT_C TInt Compare(const wchar_t* aWideCharStr) const; |
|
656 IMPORT_C TInt CompareF(const wchar_t* aWideCharStr) const; |
|
657 IMPORT_C TInt Match(const wchar_t* aWideCharStr) const; |
|
658 IMPORT_C TInt MatchF(const wchar_t* aWideCharStr) const; |
|
659 IMPORT_C TInt Find(const wchar_t* aWideCharStr) const; |
|
660 IMPORT_C TInt Find(const wchar_t* aWideCharStr,TInt aLenS ) const; |
|
661 IMPORT_C TInt FindF(const wchar_t* aWideCharStr) const; |
|
662 IMPORT_C TInt FindF(const wchar_t* aWideCharStr,TInt aLenS) const; |
|
663 |
|
664 IMPORT_C LString16& operator=(const wchar_t* aWideCharStr); |
|
665 IMPORT_C LString16& operator+=(const wchar_t* aWideCharStr); |
|
666 IMPORT_C void CopyL(const wchar_t* aWideCharStr); |
|
667 IMPORT_C void CopyFL(const wchar_t* aWideCharStr); |
|
668 IMPORT_C void CopyLCL(const wchar_t* aWideCharStr); |
|
669 IMPORT_C void CopyUCL(const wchar_t* aWideCharStr); |
|
670 IMPORT_C void CopyCPL(const wchar_t* aWideCharStr); |
|
671 IMPORT_C void InsertL(TInt aPos,const wchar_t* aWideCharStr); |
|
672 IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const wchar_t* aWideCharStr); |
|
673 IMPORT_C void AppendL(const wchar_t* aWideCharStr, TInt aLength); |
|
674 IMPORT_C void AppendL(const wchar_t* aWideCharStr); |
|
675 IMPORT_C void JustifyL(const wchar_t* aWideCharStr,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
676 IMPORT_C void AppendJustifyL(const wchar_t* aWideCharStr,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
677 IMPORT_C void AppendJustifyL(const wchar_t* aWideCharStr,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
678 |
|
679 #endif// NATIVE_WCHAR |
|
680 |
|
681 |
|
682 protected: |
|
683 |
|
684 private: |
|
685 /* |
|
686 * New capacity management API |
|
687 */ |
|
688 void ReserveL(TInt aMinRequiredCapacity); |
|
689 void ReserveCapacityGrowExponentialL(TInt aRequiredCapacity); |
|
690 void ReserveCapacityGrowExponentialL(); |
|
691 void ReserveFreeCapacityGrowExponentialL(TInt aRequiredEmptySpace); |
|
692 |
|
693 |
|
694 //---------------------------------------------------------- |
|
695 // These mutable TDes16 methods panic when called with an insufficient |
|
696 // buffer space. |
|
697 // A precondition for TDes16 use is that a sufficient |
|
698 // sufficient buffer is allocated before making calls that write to the |
|
699 // buffer. LString invalidates this precondition. |
|
700 // LString inheriting these TDes methods makes it easy |
|
701 // for developers to call them inadvertently. They have been made |
|
702 // private to ensure the misunderstanding never happens. Developers should |
|
703 // use the leaving (L suffixed) LString equivalents. |
|
704 void SetLength(TInt aLength); |
|
705 void SetMax(); |
|
706 void Copy(const TDesC8 &aDes); |
|
707 void Copy(const TDesC16 &aDes); |
|
708 void Copy(const TUint16 *aBuf,TInt aLength); |
|
709 void Copy(const TUint16 *aString); |
|
710 void Append(TChar aChar); |
|
711 void Append(const TDesC16 &aDes); |
|
712 void Append(const TUint16 *aBuf,TInt aLength); |
|
713 void Fill(TChar aChar,TInt aLength); |
|
714 void FillZ(TInt aLength); |
|
715 void NumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth); |
|
716 void AppendNumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth); |
|
717 const TUint16 *PtrZ(); |
|
718 void CopyF(const TDesC16 &aDes); |
|
719 void CopyC(const TDesC16 &aDes); |
|
720 void CopyLC(const TDesC16 &aDes); |
|
721 void CopyUC(const TDesC16 &aDes); |
|
722 void CopyCP(const TDesC16 &aDes); |
|
723 void AppendFill(TChar aChar,TInt aLength); |
|
724 void ZeroTerminate(); |
|
725 void Swap(TDes16 &aDes); |
|
726 void Insert(TInt aPos,const TDesC16 &aDes); |
|
727 void Replace(TInt aPos,TInt aLength,const TDesC16 &aDes); |
|
728 void Justify(const TDesC16 &aDes,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
729 void NumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth); |
|
730 void NumUC(TUint64 aVal, TRadix aRadix=EDecimal); |
|
731 TInt Num(TReal aVal,const TRealFormat &aFormat) __SOFTFP; |
|
732 void Num(TInt64 aVal); |
|
733 void Num(TUint64 aVal, TRadix aRadix); |
|
734 void Format(TRefByValue<const TDesC16> aFmt,...); |
|
735 void FormatList(const TDesC16 &aFmt,VA_LIST aList); |
|
736 void AppendJustify(const TDesC16 &Des,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
737 void AppendJustify(const TDesC16 &Des,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
738 void AppendJustify(const TUint16 *aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
739 void AppendJustify(const TUint16 *aZeroTerminatedString,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill); |
|
740 void AppendNumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth); |
|
741 void AppendNumUC(TUint64 aVal, TRadix aRadix=EDecimal); |
|
742 TInt AppendNum(TReal aVal,const TRealFormat &aFormat) __SOFTFP; |
|
743 void AppendNum(TInt64 aVal); |
|
744 void AppendNum(TUint64 aVal, TRadix aRadix); |
|
745 void AppendFormat(TRefByValue<const TDesC16> aFmt,TDes16Overflow *aOverflowHandler,...); |
|
746 void AppendFormat(TRefByValue<const TDesC16> aFmt,...); |
|
747 void AppendFormatList(const TDesC16 &aFmt,VA_LIST aList,TDes16Overflow *aOverflowHandler=NULL); |
|
748 // end of TDes16 methods |
|
749 //--------------------------------------------------- |
|
750 |
|
751 //---------------------------------------------------------- |
|
752 // These mutable RBuf16 methods have been privatised because |
|
753 // they make assumptions which are incompatible with the |
|
754 // general use pattern of LString16. |
|
755 void Swap(RBuf16& aRBuf); |
|
756 TInt Create(TInt aMaxLength); |
|
757 void CreateL(TInt aMaxLength); |
|
758 TInt CreateMax(TInt aMaxLength); |
|
759 void CreateMaxL(TInt aMaxLength); |
|
760 TInt Create(const TDesC16& aDes); |
|
761 void CreateL(const TDesC16& aDes); |
|
762 TInt Create(const TDesC16& aDes,TInt aMaxLength); |
|
763 void CreateL(const TDesC16& aDes,TInt aMaxLength); |
|
764 void Close(); |
|
765 void CleanupClosePushL(); |
|
766 // end of privated RBuf16 methods |
|
767 //--------------------------------------------------- |
|
768 |
|
769 void EnsureCapacityIncrementL(TInt aLengthIncrement); |
|
770 void IncreaseCapacityL(); |
|
771 |
|
772 private: |
|
773 //reserved data member for future-proofing |
|
774 TInt iReserved; |
|
775 }; |
|
776 |
|
777 |
|
778 /** |
|
779 Type alias for LString16. |
|
780 |
|
781 LString is typically used in preference to LString16 when manipulating |
|
782 Unicode text, in the same way that TDesC is typically used in |
|
783 preference to TDesC16. |
|
784 */ |
|
785 typedef LString16 LString; |
|
786 |
|
787 /** |
|
788 Type alias for LString8. |
|
789 |
|
790 LData can be used to better express intent when using an LString8 to |
|
791 manipulate raw binary (non character) data. |
|
792 */ |
|
793 typedef LString8 LData; |
|
794 |
|
795 #undef LSTRING_CONSTRUCTORS_MAY_LEAVE |
|
796 |
|
797 #endif // !ESTRING_H |