|
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 #include <e32base.h> |
|
17 #include <estring.h> |
|
18 |
|
19 const TUint KDefaultExpandSize = 16; |
|
20 |
|
21 |
|
22 /** |
|
23 Aligns the supplied capacity to the nearest growth factor |
|
24 |
|
25 For performance reasons the growth factor, KDefaultExpandSizeShift, |
|
26 is expressed as an exponent of 2 so shifting can be used to achieve the |
|
27 alignment. |
|
28 |
|
29 a KDefaultExpandSizeShift value of 4 is equivalent to 16; |
|
30 giving newCapacity = ((newCapacity / 16) + 1) * 16 |
|
31 |
|
32 @param aNewCapacity The size to be aligned |
|
33 |
|
34 @return The new, aligned capacity |
|
35 */ |
|
36 static inline TInt AlignCapacity(TInt aNewCapacity) |
|
37 { |
|
38 const TUint KDefaultExpandSizeShift = 4; |
|
39 |
|
40 return (TInt)((((TUint)aNewCapacity >> KDefaultExpandSizeShift) + 1) << KDefaultExpandSizeShift); |
|
41 } |
|
42 |
|
43 /** |
|
44 Guarantees that MaxLength() is greater than or equal to the supplied |
|
45 capacity, reallocating the supplied capacity if necessary. |
|
46 |
|
47 The actual value of MaxLength() after a call may differ from the exact |
|
48 value requested, but if it does differ it will always be greater. This |
|
49 flexibility allows the implementation to manage heap buffers more |
|
50 efficiently. |
|
51 |
|
52 The string descriptor's heap buffer may be reallocated in order to |
|
53 accommodate the new size. As a |
|
54 result, MaxLength() and Ptr() may return different values afterwards, |
|
55 and any existing raw pointers to into the descriptor data may be |
|
56 invalidated. |
|
57 |
|
58 @param aMinRequiredCapacity The minimum value of MaxLength() required |
|
59 |
|
60 @leave KErrNoMemory if the underlying buffer needs to be |
|
61 grown and there are insufficient resources to do so |
|
62 */ |
|
63 void LString16::ReserveL(TInt aMinRequiredCapacity) |
|
64 { |
|
65 if (MaxLength() < aMinRequiredCapacity) |
|
66 { |
|
67 ReAllocL(AlignCapacity(aMinRequiredCapacity)); |
|
68 } |
|
69 } |
|
70 |
|
71 |
|
72 /** |
|
73 Guarantees that MaxLength() is greater than or equal to the supplied |
|
74 integer parameter, growing the underlying heap buffer if necessary. |
|
75 |
|
76 The growth is exponential; maxLength *= 1.5 |
|
77 This is reported to give an amortised complexity of O(n) when adding |
|
78 n characters. |
|
79 If the required capacity is larger than the expanded size then the |
|
80 required capacity is used instead. |
|
81 |
|
82 The actual value of MaxLength() after a call may differ from the exact |
|
83 value requested, but if it does differ it will always be greater. This |
|
84 flexibility allows the implementation to manage heap buffers more |
|
85 efficiently. |
|
86 |
|
87 @param aRequiredCapacity The minimum value of MaxLength() required |
|
88 |
|
89 @leave KErrNoMemory if the underlying buffer needs to be |
|
90 grown and there are insufficient resources to do so |
|
91 */ |
|
92 void LString16::ReserveCapacityGrowExponentialL(TInt aRequiredCapacity) |
|
93 { |
|
94 //work in unsigned int for the appropriate shift operation |
|
95 TUint max_length = MaxLength(); |
|
96 TUint requiredCapacity = aRequiredCapacity; |
|
97 |
|
98 if (max_length < requiredCapacity) |
|
99 { |
|
100 // max_length *= 3/2; |
|
101 max_length = (max_length + (max_length << 1)) >> 1; |
|
102 |
|
103 // take the bigger of the extended buffer or the required capactiy |
|
104 ReAllocL(AlignCapacity((TInt)(max_length > requiredCapacity ? max_length : requiredCapacity))); |
|
105 } |
|
106 } |
|
107 |
|
108 /** |
|
109 Guarantees that free space in the buffer greater than or equal the |
|
110 supplied integer parameter, growing the underlying heap buffer |
|
111 if necessary. |
|
112 |
|
113 @param aRequiredEmptySpace The minimum value of free space required |
|
114 |
|
115 @leave KErrNoMemory if the underlying buffer needs to be |
|
116 grown and there are insufficient resources to do so |
|
117 */ |
|
118 void LString16::ReserveFreeCapacityGrowExponentialL(TInt aRequiredEmptySpace) |
|
119 { |
|
120 ReserveCapacityGrowExponentialL(Length() + aRequiredEmptySpace); |
|
121 } |
|
122 |
|
123 /** |
|
124 Grows the underlying buffer using the exponential growth |
|
125 function. Guarantees that MaxLength() is greater than or |
|
126 equal to 1.5 * the current MaxLength. |
|
127 |
|
128 |
|
129 @leave KErrNoMemory if the underlying buffer needs to be |
|
130 grown and there are insufficient resources to do so |
|
131 */ |
|
132 void LString16::ReserveCapacityGrowExponentialL() |
|
133 { |
|
134 ReserveCapacityGrowExponentialL(MaxLength() + 1); |
|
135 } |
|
136 |
|
137 |
|
138 /** |
|
139 Default constructor. |
|
140 |
|
141 Constructs a zero-length 16-bit resizable string descriptor. |
|
142 |
|
143 Note that the resulting object owns no allocated memory yet. This |
|
144 default constructor never leaves. |
|
145 */ |
|
146 EXPORT_C LString16::LString16() |
|
147 : iReserved(0) |
|
148 { |
|
149 } |
|
150 |
|
151 /** |
|
152 Destructor. |
|
153 |
|
154 Frees any heap-allocated resources owned by this string descriptor. It |
|
155 is safe to rely on this destructor to perform all necessary cleanup; |
|
156 it is not necessary use the cleanup stack or to call Close() manually. |
|
157 |
|
158 @see RBuf16::Close |
|
159 */ |
|
160 EXPORT_C LString16::~LString16() |
|
161 { |
|
162 RBuf16::Close(); |
|
163 } |
|
164 |
|
165 /** |
|
166 Constructor to create a 16-bit resizable string descriptor with an |
|
167 initial capacity. |
|
168 |
|
169 The function allocates sufficient memory to contain descriptor data up to |
|
170 the specified initial maximum length. |
|
171 |
|
172 The current length of the descriptor is set to zero. The maximum length of |
|
173 the descriptor is set to the specified value. |
|
174 |
|
175 @param aMaxLength The maximum length of the descriptor. |
|
176 |
|
177 @leave KErrNoMemory If there is insufficient memory. |
|
178 |
|
179 @see RBuf16::CreateL |
|
180 */ |
|
181 EXPORT_C LString16::LString16(TInt aMaxLength) |
|
182 : iReserved(0) |
|
183 { |
|
184 RBuf16::CreateL(aMaxLength); |
|
185 } |
|
186 |
|
187 /** |
|
188 Constructor to create a 16-bit resizable string descriptor from a |
|
189 pre-allocated heap descriptor. |
|
190 |
|
191 Transfers ownership of the specified heap descriptor to this object. |
|
192 |
|
193 @param aHBuf The heap descriptor to be transferred to this object. |
|
194 This pointer can be NULL, which means that a zero length |
|
195 16-bit resizable string descriptor is created. |
|
196 |
|
197 @see RBuf16::RBuf16(HBufC16*) |
|
198 */ |
|
199 EXPORT_C LString16::LString16(HBufC16* aHBuf) |
|
200 : iReserved(0) |
|
201 { |
|
202 if (aHBuf) |
|
203 RBuf16::Assign (aHBuf); |
|
204 } |
|
205 |
|
206 /** |
|
207 Constructor to create a 16-bit resizable string descriptor from a |
|
208 pre-allocated raw heap buffer. |
|
209 |
|
210 The allocated memory forms the buffer for this string descriptor. The |
|
211 current length of the descriptor is set to zero. |
|
212 |
|
213 @param aHeapCell The allocated memory to be assigned to this object. This |
|
214 pointer can be NULL, which means that a zero length 16-bit |
|
215 resizable buffer descriptor is created. |
|
216 @param aMaxLength The maximum length of the constructed string descriptor. |
|
217 |
|
218 @panic USER 8 If the specified maximum length is greater then the size of |
|
219 the allocated heap cell, or the specified maximum length |
|
220 is NOT zero when the pointer to the heap cell is NULL. |
|
221 |
|
222 @see RBuf16::Assign() |
|
223 */ |
|
224 EXPORT_C LString16::LString16(TUint16* aHeapCell,TInt aMaxLength) |
|
225 : iReserved(0) |
|
226 { |
|
227 RBuf16::Assign(aHeapCell, aMaxLength); |
|
228 } |
|
229 |
|
230 /** |
|
231 Constructor to create a 16-bit resizable string descriptor from a |
|
232 pre-allocated raw heap buffer. |
|
233 |
|
234 The allocated memory forms the buffer for this string descriptor. The |
|
235 current length of the descriptor is set to the value of the second |
|
236 parameter. |
|
237 |
|
238 @param aHeapCell The allocated memory to be assigned to this object. |
|
239 @param aLength The length of the resulting string descriptor. |
|
240 @param aMaxLength The maximum length of the resulting string descriptor. |
|
241 |
|
242 @panic USER 8 If the specified maximum length is greater then the size of |
|
243 the allocated heap cell, or the specified length is greater then |
|
244 the specified maximum length, or the specified maximum length |
|
245 is NOT zero when the pointer to the heap cell is NULL. |
|
246 |
|
247 @see RBuf16::Assign() |
|
248 */ |
|
249 EXPORT_C LString16::LString16(TUint16* aHeapCell,TInt aLength,TInt aMaxLength) |
|
250 : iReserved(0) |
|
251 { |
|
252 RBuf16::Assign(aHeapCell, aLength, aMaxLength); |
|
253 } |
|
254 |
|
255 /** |
|
256 Constructor to create a 16-bit resizable string descriptor to contain |
|
257 a copy of the specified (source) descriptor, or leave on failure. |
|
258 |
|
259 The constructor allocates sufficient memory so that this string |
|
260 descriptor's maximum length is the same as the length of the source |
|
261 descriptor. Both the current length and the maximum length of this |
|
262 string descriptor are set to the length of the source descriptor. |
|
263 |
|
264 The data contained in the source descriptor is copied into this string |
|
265 descriptor. |
|
266 |
|
267 @param aDes Source descriptor to be copied into this object. |
|
268 |
|
269 @leave KErrNoMemory If there is insufficient memory. |
|
270 |
|
271 @see RBuf16::CreateL() |
|
272 */ |
|
273 EXPORT_C LString16::LString16(const TDesC16& aDes) |
|
274 : iReserved(0) |
|
275 { |
|
276 RBuf16::CreateL(aDes); |
|
277 } |
|
278 |
|
279 /** |
|
280 Copies data into this 16-bit string descriptor, replacing any existing |
|
281 data, and expanding its heap buffer to accommodate if necessary. |
|
282 |
|
283 The length of this descriptor is set to reflect the new data. |
|
284 |
|
285 This operation may cause the target string descriptor's heap buffer to |
|
286 be reallocated in order to accommodate the new data. As a result, |
|
287 MaxLength() and Ptr() may return different values afterwards, and any |
|
288 existing raw pointers to into the descriptor data may be invalidated. |
|
289 |
|
290 Note that the automatic resizing performed is a change to the |
|
291 functionality of this operation compared to other descriptor |
|
292 classes. This change is only active on objects directly declared |
|
293 LString16; when LString16 instances are instead manipulated via |
|
294 references to TDes16 or TDesC16, the standard (non-resizing, panicing) |
|
295 variant is invoked. |
|
296 |
|
297 @param aDes A 16-bit non-modifiable descriptor. |
|
298 |
|
299 @return A reference to this 16-bit string descriptor. |
|
300 |
|
301 @leave KErrNoMemory If the heap buffer of the string descriptor being |
|
302 assigned to needs to be expanded, but there is |
|
303 insufficient memory to do so |
|
304 |
|
305 @see LString16::CopyL |
|
306 */ |
|
307 EXPORT_C LString16& LString16::operator=(const TDesC16& aDes) |
|
308 { |
|
309 CopyL(aDes); |
|
310 return *this; |
|
311 } |
|
312 |
|
313 |
|
314 /** |
|
315 Transfers ownership of the specified 16-bit resizable descriptor's this object. |
|
316 |
|
317 @param aBuf The source 16-bit resizable buffer. The ownership of this |
|
318 object's buffer is to be transferred. |
|
319 |
|
320 @return A reference to this 16-bit string descriptor. |
|
321 |
|
322 @see Assign() |
|
323 */ |
|
324 EXPORT_C LString16& LString16::operator=(HBufC16* aBuf) |
|
325 { |
|
326 Assign(aBuf); |
|
327 return *this; |
|
328 } |
|
329 |
|
330 |
|
331 /** |
|
332 Copies data into this 16-bit string descriptor, replacing any existing |
|
333 data, and expanding its heap buffer to accommodate if necessary. |
|
334 |
|
335 The length of this descriptor is set to reflect the new data. |
|
336 |
|
337 This leaving variant of the standard, non-leaving descriptor method |
|
338 differs in that this operation may cause the string descriptor's heap |
|
339 buffer to be reallocated in order to accommodate the new data. As a |
|
340 result, MaxLength() and Ptr() may return different values afterwards, |
|
341 and any existing raw pointers to into the descriptor data may be |
|
342 invalidated. |
|
343 |
|
344 @param aDes A 16-bit non-modifiable descriptor. |
|
345 |
|
346 @leave KErrNoMemory If the heap buffer of the string descriptor being |
|
347 assigned to needs to be expanded, but there is |
|
348 insufficient memory to do so |
|
349 |
|
350 @see LString16::operator= |
|
351 @see TDes16::Copy |
|
352 */ |
|
353 EXPORT_C void LString16::CopyL(const TDesC16& aDes) |
|
354 { |
|
355 ReserveL(aDes.Length()); |
|
356 RBuf16::Copy(aDes); |
|
357 } |
|
358 |
|
359 /** |
|
360 Copy constructor to create a 16-bit resizable string descriptor to |
|
361 contain a copy of the specified (source) string descriptor's data, or |
|
362 leave on failure. |
|
363 |
|
364 The constructor allocates sufficient memory so that this string |
|
365 descriptor's maximum length is the same as the length of the source |
|
366 string descriptor. Both the current length and the maximum length of |
|
367 this string descriptor are set to the length of the source descriptor. |
|
368 |
|
369 The data contained in the source string descriptor is copied into this |
|
370 string descriptor. |
|
371 |
|
372 @param aDes Source string descriptor to be copied into this object. |
|
373 |
|
374 @leave KErrNoMemory If there is insufficient memory. |
|
375 |
|
376 @see RBuf16::CreateL() |
|
377 */ |
|
378 EXPORT_C LString16::LString16(const LString16& aDes) |
|
379 : iReserved(0) |
|
380 { |
|
381 RBuf16::CreateL(aDes); |
|
382 } |
|
383 |
|
384 |
|
385 /** |
|
386 Copies data into this 16-bit string descriptor, replacing any existing |
|
387 data, and expanding its heap buffer to accommodate if necessary. |
|
388 |
|
389 The length of this descriptor is set to reflect the new data. |
|
390 |
|
391 This operation may cause the target string descriptor's heap buffer to |
|
392 be reallocated in order to accommodate the new data. As a result, |
|
393 MaxLength() and Ptr() may return different values afterwards, and any |
|
394 existing raw pointers to into the descriptor data may be invalidated. |
|
395 |
|
396 Note that the automatic resizing performed is a change to the |
|
397 functionality of this operation compared to other descriptor |
|
398 classes. This change is only active on objects directly declared |
|
399 LString16; when LString16 instances are instead manipulated via |
|
400 references to TDes16 or TDesC16, the standard (non-resizing, panicing) |
|
401 variant is invoked. |
|
402 |
|
403 @param aDes A 16-bit string descriptor. |
|
404 |
|
405 @return A reference to this 16-bit string descriptor. |
|
406 |
|
407 @leave KErrNoMemory If the heap buffer of the string descriptor being |
|
408 assigned to needs to be expanded, but there is |
|
409 insufficient memory to do so |
|
410 |
|
411 @see LString16::CopyL |
|
412 */ |
|
413 EXPORT_C LString16& LString16::operator=(const LString16& aDes) |
|
414 { |
|
415 CopyL(aDes); |
|
416 return *this; |
|
417 } |
|
418 |
|
419 /** |
|
420 Constructor to create a 16-bit resizable string descriptor containing |
|
421 a copy of the specified (source) zero-terminated string data, or leave |
|
422 on failure. |
|
423 |
|
424 The constructor allocates sufficient memory so that this string |
|
425 descriptor's maximum length is the same as the length of the source |
|
426 string. Both the current length and the maximum length of this string |
|
427 descriptor are set to the length of the source string. |
|
428 |
|
429 The data contained in the source string is copied into this string |
|
430 descriptor. The zero terminator is not copied. |
|
431 |
|
432 @param aZeroTerminatedString A pointer to a zero-terminated string |
|
433 |
|
434 @leave KErrNoMemory If there is insufficient memory. |
|
435 |
|
436 @see LString16::CopyL |
|
437 */ |
|
438 EXPORT_C LString16::LString16(const TUint16* aZeroTerminatedString) |
|
439 : iReserved(0) |
|
440 { |
|
441 CopyL(aZeroTerminatedString); |
|
442 } |
|
443 |
|
444 /** |
|
445 Copies data into this 16-bit string descriptor, replacing any existing |
|
446 data, and expanding its heap buffer to accommodate if necessary. |
|
447 |
|
448 The length of this descriptor is set to reflect the new data. |
|
449 |
|
450 This operation may cause the target string descriptor's heap buffer to |
|
451 be reallocated in order to accommodate the new data. As a result, |
|
452 MaxLength() and Ptr() may return different values afterwards, and any |
|
453 existing raw pointers to into the descriptor data may be invalidated. |
|
454 |
|
455 Note that the automatic resizing performed is a change to the |
|
456 functionality of this operation compared to other descriptor |
|
457 classes. This change is only active on objects directly declared |
|
458 LString16; when LString16 instances are instead manipulated via |
|
459 references to TDes16 or TDesC16, the standard (non-resizing, panicing) |
|
460 variant is invoked. |
|
461 |
|
462 @param aZeroTerminatedString A pointer to a zero-terminated string |
|
463 |
|
464 @return A reference to this 16-bit string descriptor. |
|
465 |
|
466 @leave KErrNoMemory If the heap buffer of the string descriptor being |
|
467 assigned to needs to be expanded, but there is |
|
468 insufficient memory to do so |
|
469 |
|
470 @see LString16::CopyL |
|
471 */ |
|
472 EXPORT_C LString16& LString16::operator=(const TUint16* aZeroTerminatedString) |
|
473 { |
|
474 CopyL(aZeroTerminatedString); |
|
475 return *this; |
|
476 } |
|
477 |
|
478 /** |
|
479 Copies data into this 16-bit string descriptor, replacing any existing |
|
480 data, and expanding its heap buffer to accommodate if necessary. |
|
481 |
|
482 The length of this descriptor is set to reflect the new data. |
|
483 |
|
484 This leaving variant of the standard, non-leaving descriptor method |
|
485 differs in that this operation may cause the string descriptor's heap |
|
486 buffer to be reallocated in order to accommodate the new data. As a |
|
487 result, MaxLength() and Ptr() may return different values afterwards, |
|
488 and any existing raw pointers to into the descriptor data may be |
|
489 invalidated. |
|
490 |
|
491 @param aZeroTerminatedString A pointer to a zero-terminated string |
|
492 |
|
493 @leave KErrNoMemory If the heap buffer of the string descriptor being |
|
494 assigned to needs to be expanded, but there is |
|
495 insufficient memory to do so |
|
496 |
|
497 @see LString16::operator= |
|
498 @see TDes16::Copy |
|
499 */ |
|
500 EXPORT_C void LString16::CopyL(const TUint16* aZeroTerminatedString) |
|
501 { |
|
502 ReserveL(User::StringLength(aZeroTerminatedString)); |
|
503 RBuf16::Copy(aZeroTerminatedString); |
|
504 } |
|
505 |
|
506 /** |
|
507 Copies 8-bit descriptor data into this 16-bit string descriptor, |
|
508 replacing any existing data, and expanding its heap buffer to |
|
509 accommodate if necessary. |
|
510 |
|
511 The length of this descriptor is set to reflect the new data. |
|
512 |
|
513 Each 8-bit character value is widened to a 16-bit character value as |
|
514 part of the copying process. |
|
515 |
|
516 This leaving variant of the standard, non-leaving descriptor method |
|
517 differs in that this operation may cause the string descriptor's heap |
|
518 buffer to be reallocated in order to accommodate the new data. As a |
|
519 result, MaxLength() and Ptr() may return different values afterwards, |
|
520 and any existing raw pointers to into the descriptor data may be |
|
521 invalidated. |
|
522 |
|
523 @param aDes An 8 bit non modifiable descriptor. |
|
524 |
|
525 @leave KErrNoMemory If the heap buffer of the string descriptor being |
|
526 assigned to needs to be expanded, but there is |
|
527 insufficient memory to do so |
|
528 |
|
529 @see LString16::operator= |
|
530 @see TDes16::Copy |
|
531 */ |
|
532 EXPORT_C void LString16::CopyL(const TDesC8& aDes) |
|
533 { |
|
534 ReserveL(aDes.Length()); |
|
535 RBuf16::Copy(aDes); |
|
536 } |
|
537 |
|
538 /** |
|
539 Copies data into this 16-bit string descriptor, replacing any existing |
|
540 data, and expanding its heap buffer to accommodate if necessary. |
|
541 |
|
542 The length of this descriptor is set according to the second |
|
543 parameter. |
|
544 |
|
545 This leaving variant of the standard, non-leaving descriptor method |
|
546 differs in that this operation may cause the string descriptor's heap |
|
547 buffer to be reallocated in order to accommodate the new data. As a |
|
548 result, MaxLength() and Ptr() may return different values afterwards, |
|
549 and any existing raw pointers to into the descriptor data may be |
|
550 invalidated. |
|
551 |
|
552 @param aBuf The start address of data to be copied. |
|
553 @param aLength The length of data to be copied. |
|
554 |
|
555 @leave KErrNoMemory If the heap buffer of the string descriptor being |
|
556 assigned to needs to be expanded, but there is |
|
557 insufficient memory to do so |
|
558 |
|
559 @panic USER 11 if aLength is negative. |
|
560 |
|
561 @see TDes16::Copy |
|
562 */ |
|
563 EXPORT_C void LString16::CopyL(const TUint16* aBuf,TInt aLength) |
|
564 { |
|
565 ReserveL(aLength); |
|
566 RBuf16::Copy(aBuf, aLength); |
|
567 } |
|
568 |
|
569 |
|
570 /** |
|
571 Sets the length of the data represented by the string descriptor to |
|
572 the specified value. |
|
573 |
|
574 This leaving variant of the standard, non-leaving descriptor method |
|
575 differs in that this operation may cause the string descriptor's heap |
|
576 buffer to be reallocated in order to accommodate the new data. As a |
|
577 result, MaxLength() and Ptr() may return different values afterwards, |
|
578 and any existing raw pointers to into the descriptor data may be |
|
579 invalidated. |
|
580 |
|
581 @param aLength The new length of the descriptor. |
|
582 |
|
583 @leave KErrNoMemory if the underlying buffer needs to be |
|
584 grown and there are insufficient resources to do so |
|
585 |
|
586 @panic USER 11 if aLength is negative |
|
587 */ |
|
588 EXPORT_C void LString16::SetLengthL(TInt aLength) |
|
589 { |
|
590 ReserveL(aLength); |
|
591 RBuf16::SetLength(aLength); |
|
592 } |
|
593 |
|
594 |
|
595 /** |
|
596 Sets the storage space allocated to this descriptor to the specified |
|
597 value by growing or compressing its buffer size. |
|
598 |
|
599 If the current length of the descriptor is greater than the specified |
|
600 max length, length is truncated to max length. |
|
601 |
|
602 This leaving variant of the standard, non-leaving descriptor method |
|
603 differs in that this operation may cause the string descriptor's heap |
|
604 buffer to be reallocated in order to accommodate the new data. As a |
|
605 result, MaxLength() and Ptr() may return different values afterwards, |
|
606 and any existing raw pointers to into the descriptor data may be |
|
607 invalidated. |
|
608 |
|
609 @param aMaxLength The new maximum length of the descriptor. |
|
610 |
|
611 @leave KErrNoMemory if the the buffer needs to be |
|
612 reallocated and there are insufficient resources to do so |
|
613 |
|
614 @panic USER 11 if aLength is negative |
|
615 */ |
|
616 EXPORT_C void LString16::SetMaxLengthL(TInt aMaxLength) |
|
617 { |
|
618 if (MaxLength() == aMaxLength) |
|
619 { |
|
620 return; |
|
621 } |
|
622 |
|
623 if (Length() > aMaxLength) |
|
624 { |
|
625 // truncate the current length |
|
626 RBuf16::SetLength(aMaxLength); |
|
627 } |
|
628 |
|
629 ReAllocL(aMaxLength); |
|
630 } |
|
631 |
|
632 |
|
633 /** |
|
634 Ensures that the remaining unused space is more than the supplied value. |
|
635 |
|
636 May reallocate a larger storage space to meet the requirement. |
|
637 As a result MaxLength() and Ptr() may return different values afterwards, |
|
638 and any existing raw pointers to into the descriptor data may be |
|
639 invalidated. |
|
640 |
|
641 Typically, you use this method to reserve a known amount of required space |
|
642 in one go instead of relying on the automatic growth pattern. |
|
643 |
|
644 @param aExtraSpaceLength The extra space required. |
|
645 |
|
646 @leave KErrNoMemory if the the buffer needs to be |
|
647 reallocated and there are insufficient resources to do so. |
|
648 |
|
649 @panic USER 11 if aLength is negative |
|
650 */ |
|
651 EXPORT_C void LString16::ReserveFreeCapacityL(TInt aExtraSpaceLength) |
|
652 { |
|
653 ReserveL(Length() + aExtraSpaceLength); |
|
654 } |
|
655 |
|
656 |
|
657 /** |
|
658 Re-initialises the descriptor destroying its payload |
|
659 |
|
660 */ |
|
661 EXPORT_C void LString16::Reset() |
|
662 { |
|
663 RBuf16::Close(); |
|
664 } |
|
665 |
|
666 |
|
667 /** |
|
668 Re-allocates a smaller descriptor buffer space to the current |
|
669 descriptor length |
|
670 |
|
671 This may cause the string descriptor's heap buffer to be reallocated |
|
672 in order to accommodate the new data. As a |
|
673 result, MaxLength() and Ptr() may return different values afterwards, |
|
674 and any existing raw pointers to into the descriptor data may be |
|
675 invalidated. |
|
676 |
|
677 If there is insufficient memory to re-allocate the buffer then the |
|
678 descriptor left unchanged |
|
679 */ |
|
680 EXPORT_C void LString16::Compress() |
|
681 { |
|
682 TInt length = Length(); |
|
683 if (MaxLength() > length) |
|
684 { |
|
685 ReAlloc(length); |
|
686 } |
|
687 } |
|
688 |
|
689 |
|
690 /** |
|
691 Appends data onto the end of this descriptor's data. |
|
692 |
|
693 The length of this descriptor is incremented to reflect the new content. |
|
694 |
|
695 This leaving variant of the standard, non-leaving descriptor method |
|
696 differs in that this operation may cause the string descriptor's heap |
|
697 buffer to be reallocated in order to accommodate the new data. As a |
|
698 result, MaxLength() and Ptr() may return different values afterwards, |
|
699 and any existing raw pointers to into the descriptor data may be |
|
700 invalidated. |
|
701 |
|
702 @param aChar A single character to be appended. The length of the descriptor |
|
703 is incremented by one. |
|
704 |
|
705 @leave KErrNoMemory if the underlying buffer needs to be |
|
706 grown and there are insufficient resources to do so |
|
707 |
|
708 @see LString16::operator+= |
|
709 */ |
|
710 EXPORT_C void LString16::AppendL(TChar aChar) |
|
711 { |
|
712 ReserveFreeCapacityGrowExponentialL(1); |
|
713 RBuf16::Append(aChar); |
|
714 } |
|
715 |
|
716 /** |
|
717 Appends data onto the end of this descriptor's data. |
|
718 |
|
719 The length of this descriptor is incremented to reflect the new content. |
|
720 |
|
721 This leaving variant of the standard, non-leaving descriptor method |
|
722 differs in that this operation may cause the string descriptor's heap |
|
723 buffer to be reallocated in order to accommodate the new data. As a |
|
724 result, MaxLength() and Ptr() may return different values afterwards, |
|
725 and any existing raw pointers to into the descriptor data may be |
|
726 invalidated. |
|
727 |
|
728 @param aChar A single character to be appended. The length of the descriptor |
|
729 is incremented by one. |
|
730 |
|
731 @leave KErrNoMemory if the underlying buffer needs to be |
|
732 grown and there are insufficient resources to do so |
|
733 |
|
734 @see LString16::AppendL |
|
735 */ |
|
736 EXPORT_C LString16& LString16::operator+=(TChar aChar) |
|
737 { |
|
738 AppendL(aChar); |
|
739 return *this; |
|
740 } |
|
741 |
|
742 /** |
|
743 Appends data onto the end of this descriptor's data. |
|
744 |
|
745 The length of this descriptor is incremented to reflect the new content. |
|
746 |
|
747 This leaving variant of the standard, non-leaving descriptor method |
|
748 differs in that this operation may cause the string descriptor's heap |
|
749 buffer to be reallocated in order to accommodate the new data. As a |
|
750 result, MaxLength() and Ptr() may return different values afterwards, |
|
751 and any existing raw pointers to into the descriptor data may be |
|
752 invalidated. |
|
753 |
|
754 @param aDes A 16-bit non modifiable descriptor whose data is to be appended. |
|
755 |
|
756 @leave KErrNoMemory if the underlying buffer needs to be |
|
757 grown and there are insufficient resources to do so |
|
758 */ |
|
759 EXPORT_C void LString16::AppendL(const TDesC16& aDes) |
|
760 { |
|
761 ReserveFreeCapacityGrowExponentialL(aDes.Length()); |
|
762 RBuf16::Append(aDes); |
|
763 } |
|
764 |
|
765 /** |
|
766 Appends data onto the end of this descriptor's data. |
|
767 |
|
768 The length of this descriptor is incremented to reflect the new content. |
|
769 |
|
770 This leaving variant of the standard, non-leaving descriptor method |
|
771 differs in that this operation may cause the string descriptor's heap |
|
772 buffer to be reallocated in order to accommodate the new data. As a |
|
773 result, MaxLength() and Ptr() may return different values afterwards, |
|
774 and any existing raw pointers to into the descriptor data may be |
|
775 invalidated. |
|
776 |
|
777 @param aDes A 16-bit non modifiable descriptor whose data is to be appended. |
|
778 |
|
779 @leave KErrNoMemory if the underlying buffer needs to be |
|
780 grown and there are insufficient resources to do so |
|
781 |
|
782 @see LString16::AppendL |
|
783 */ |
|
784 EXPORT_C LString16& LString16::operator+=(const TDesC16& aDes) |
|
785 { |
|
786 AppendL(aDes); |
|
787 return *this; |
|
788 } |
|
789 |
|
790 /** |
|
791 Appends data onto the end of this descriptor's data. |
|
792 |
|
793 The length of this descriptor is incremented to reflect the new content. |
|
794 |
|
795 This leaving variant of the standard, non-leaving descriptor method |
|
796 differs in that this operation may cause the string descriptor's heap |
|
797 buffer to be reallocated in order to accommodate the new data. As a |
|
798 result, MaxLength() and Ptr() may return different values afterwards, |
|
799 and any existing raw pointers to into the descriptor data may be |
|
800 invalidated. |
|
801 |
|
802 @param aBuf A pointer to the data to be copied. |
|
803 @param aLength The length of data to be copied. |
|
804 |
|
805 @leave KErrNoMemory if the underlying buffer needs to be |
|
806 grown and there are insufficient resources to do so |
|
807 |
|
808 @panic USER 17 if aLength is negative. |
|
809 */ |
|
810 EXPORT_C void LString16::AppendL(const TUint16* aBuf,TInt aLength) |
|
811 { |
|
812 ReserveFreeCapacityGrowExponentialL(aLength); |
|
813 RBuf16::Append(aBuf, aLength); |
|
814 } |
|
815 |
|
816 /** |
|
817 Fills the descriptor's data area with the specified character, replacing any |
|
818 existing data. |
|
819 |
|
820 The descriptor is filled with the specified number of characters, |
|
821 and its length is changed to reflect this. |
|
822 |
|
823 This leaving variant of the standard, non-leaving descriptor method |
|
824 differs in that this operation may cause the string descriptor's heap |
|
825 buffer to be reallocated in order to accommodate the new data. As a |
|
826 result, MaxLength() and Ptr() may return different values afterwards, |
|
827 and any existing raw pointers to into the descriptor data may be |
|
828 invalidated. |
|
829 |
|
830 @param aChar The fill character. |
|
831 @param aLength The new length of the descriptor and the number of fill characters |
|
832 to be copied into it. |
|
833 |
|
834 @leave KErrNoMemory if the underlying buffer needs to be |
|
835 grown and there are insufficient resources to do so |
|
836 |
|
837 @panic USER 11 if aLength is negative |
|
838 */ |
|
839 EXPORT_C void LString16::FillL(TChar aChar,TInt aLength) |
|
840 { |
|
841 ReserveL(aLength); |
|
842 RBuf16::Fill(aChar, aLength); |
|
843 } |
|
844 |
|
845 /** |
|
846 Fills the descriptor's data area with binary zeroes, i.e. 0x0000, replacing any |
|
847 existing data, and changes its length. |
|
848 |
|
849 The descriptor is filled with the specified number of binary zeroes. |
|
850 The descriptor's length is changed to reflect this. |
|
851 |
|
852 This leaving variant of the standard, non-leaving descriptor method |
|
853 differs in that this operation may cause the string descriptor's heap |
|
854 buffer to be reallocated in order to accommodate the new data. As a |
|
855 result, MaxLength() and Ptr() may return different values afterwards, |
|
856 and any existing raw pointers to into the descriptor data may be |
|
857 invalidated. |
|
858 |
|
859 @param aLength The new length of the descriptor and the number of binary zeroes |
|
860 to be copied into it. |
|
861 |
|
862 @leave KErrNoMemory if the underlying buffer needs to be |
|
863 grown and there are insufficient resources to do so |
|
864 |
|
865 @panic USER 11 if aLength is negative |
|
866 */ |
|
867 EXPORT_C void LString16::FillZL(TInt aLength) |
|
868 { |
|
869 ReserveL(aLength); |
|
870 RBuf16::FillZ(aLength); |
|
871 } |
|
872 |
|
873 /** |
|
874 Converts the specified unsigned integer into a fixed width character |
|
875 representation based on the specified number system and copies the conversion |
|
876 into this descriptor, replacing any existing data. |
|
877 |
|
878 The length of this descriptor is set to reflect the new data. |
|
879 |
|
880 The function generates the exact number of specified characters, either padding |
|
881 to the left with character zeroes or discarding low order characters as necessary. |
|
882 |
|
883 When a hexadecimal conversion is specified, hexadecimal characters are in |
|
884 lower case. |
|
885 |
|
886 This function is equivalent to using Format() with parameters which specify: |
|
887 |
|
888 1. a fixed length target field |
|
889 |
|
890 2. padding with zero characters, for example "%08x". |
|
891 |
|
892 When this is the case, always use NumFixedWidth() in preference |
|
893 to Format() as it is more efficient. |
|
894 |
|
895 This leaving variant of the standard, non-leaving descriptor method |
|
896 differs in that this operation may cause the string descriptor's heap |
|
897 buffer to be reallocated in order to accommodate the new data. As a |
|
898 result, MaxLength() and Ptr() may return different values afterwards, |
|
899 and any existing raw pointers to into the descriptor data may be |
|
900 invalidated. |
|
901 |
|
902 @param aVal The unsigned integer value. |
|
903 @param aRadix The number system representation for the unsigned integer. |
|
904 @param aWidth The number of characters: to be used to contain the conversion, |
|
905 to be copied into this descriptor. |
|
906 |
|
907 @leave KErrNoMemory if the underlying buffer needs to be |
|
908 grown and there are insufficient resources to do so |
|
909 */ |
|
910 EXPORT_C void LString16::NumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth) |
|
911 { |
|
912 Zero(); |
|
913 AppendNumFixedWidthL(aVal, aRadix, aWidth); |
|
914 } |
|
915 |
|
916 /** |
|
917 Converts the specified unsigned integer into a fixed width character |
|
918 representation based on the specified number system and appends the conversion |
|
919 onto the end of this descriptor's data. |
|
920 |
|
921 The length of this descriptor is incremented to reflect the new content. |
|
922 |
|
923 The function generates the exact number of specified characters, either padding |
|
924 to the left with character zeroes or discarding low order characters as |
|
925 necessary. |
|
926 |
|
927 When a hexadecimal conversion is specified, hexadecimal characters are in |
|
928 lower case. |
|
929 |
|
930 This leaving variant of the standard, non-leaving descriptor method |
|
931 differs in that this operation may cause the string descriptor's heap |
|
932 buffer to be reallocated in order to accommodate the new data. As a |
|
933 result, MaxLength() and Ptr() may return different values afterwards, |
|
934 and any existing raw pointers to into the descriptor data may be |
|
935 invalidated. |
|
936 |
|
937 @param aVal The unsigned integer value. |
|
938 @param aRadix The number system representation for the unsigned integer. |
|
939 @param aWidth The number of characters to be used to contain the conversion, |
|
940 and to be appended to this descriptor. |
|
941 |
|
942 @leave KErrNoMemory if the underlying buffer needs to be |
|
943 grown and there are insufficient resources to do so |
|
944 */ |
|
945 EXPORT_C void LString16::AppendNumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth) |
|
946 { |
|
947 ReserveFreeCapacityGrowExponentialL(aWidth); |
|
948 RBuf16::AppendNumFixedWidth(aVal, aRadix, aWidth); |
|
949 } |
|
950 |
|
951 /** |
|
952 Appends a zero terminator onto the end of this descriptor's data and returns |
|
953 a pointer to the data. |
|
954 |
|
955 The length of the descriptor is not changed, but the capacity of the |
|
956 descriptor may need to be grown to accommodate the zero terminator. |
|
957 |
|
958 This leaving variant of the standard, non-leaving descriptor method |
|
959 differs in that this operation may cause the string descriptor's heap |
|
960 buffer to be reallocated in order to accommodate the new data. As a |
|
961 result, MaxLength() and Ptr() may return different values afterwards, |
|
962 and any existing raw pointers to into the descriptor data may be |
|
963 invalidated. |
|
964 |
|
965 @return A pointer to the descriptor's zero terminated data. |
|
966 |
|
967 @leave KErrNoMemory if the underlying buffer needs to be |
|
968 grown and there are insufficient resources to do so |
|
969 */ |
|
970 EXPORT_C const TUint16 *LString16::PtrZL() |
|
971 { |
|
972 ReserveFreeCapacityL(1); |
|
973 return RBuf16::PtrZ(); |
|
974 } |
|
975 |
|
976 /** |
|
977 Copies and folds data from the specified descriptor into this descriptor replacing |
|
978 any existing data. |
|
979 |
|
980 The length of this descriptor is set to reflect the new |
|
981 data. |
|
982 |
|
983 Note that folding is locale-independent behaviour. It is also important to |
|
984 note that there can be no guarantee that folding is in any way culturally |
|
985 appropriate, and should not be used when dealing with strings in natural |
|
986 language. |
|
987 |
|
988 This leaving variant of the standard, non-leaving descriptor method |
|
989 differs in that this operation may cause the string descriptor's heap |
|
990 buffer to be reallocated in order to accommodate the new data. As a |
|
991 result, MaxLength() and Ptr() may return different values afterwards, |
|
992 and any existing raw pointers to into the descriptor data may be |
|
993 invalidated. |
|
994 |
|
995 @param aDes A 16-bit non-modifiable descriptor. |
|
996 |
|
997 @leave KErrNoMemory if the underlying buffer needs to be |
|
998 grown and there are insufficient resources to do so |
|
999 */ |
|
1000 EXPORT_C void LString16::CopyFL(const TDesC16& aDes) |
|
1001 { |
|
1002 ReserveL(aDes.Length()); |
|
1003 RBuf16::CopyF(aDes); |
|
1004 } |
|
1005 |
|
1006 /** |
|
1007 Copies and collates data from the specified descriptor |
|
1008 into this descriptor replacing any existing data. |
|
1009 |
|
1010 The length of this descriptor is set to reflect the new data. |
|
1011 |
|
1012 This leaving variant of the standard, non-leaving descriptor method |
|
1013 differs in that this operation may cause the string descriptor's heap |
|
1014 buffer to be reallocated in order to accommodate the new data. As a |
|
1015 result, MaxLength() and Ptr() may return different values afterwards, |
|
1016 and any existing raw pointers to into the descriptor data may be |
|
1017 invalidated. |
|
1018 |
|
1019 @param aDes A 16-bit non-modifiable descriptor. |
|
1020 |
|
1021 @leave KErrNoMemory if the underlying buffer needs to be |
|
1022 grown and there are insufficient resources to do so |
|
1023 */ |
|
1024 EXPORT_C void LString16::CopyCL(const TDesC16& aDes) |
|
1025 { |
|
1026 ReserveL(aDes.Length()); |
|
1027 RBuf16::CopyC(aDes); |
|
1028 } |
|
1029 |
|
1030 /** |
|
1031 Copies text from the specified descriptor and converts it to lower case before |
|
1032 putting it into this descriptor, replacing any existing data. |
|
1033 |
|
1034 The length of this descriptor is set to reflect the new data. |
|
1035 |
|
1036 Conversion to lower case is implemented as appropriate to the current locale. |
|
1037 |
|
1038 This leaving variant of the standard, non-leaving descriptor method |
|
1039 differs in that this operation may cause the string descriptor's heap |
|
1040 buffer to be reallocated in order to accommodate the new data. As a |
|
1041 result, MaxLength() and Ptr() may return different values afterwards, |
|
1042 and any existing raw pointers to into the descriptor data may be |
|
1043 invalidated. |
|
1044 |
|
1045 @param aDes A 16-bit non modifiable descriptor. |
|
1046 |
|
1047 @leave KErrNoMemory if the underlying buffer needs to be |
|
1048 grown and there are insufficient resources to do so |
|
1049 */ |
|
1050 EXPORT_C void LString16::CopyLCL(const TDesC16& aDes) |
|
1051 { |
|
1052 ReserveL(aDes.Length()); |
|
1053 RBuf16::CopyLC(aDes); |
|
1054 } |
|
1055 |
|
1056 /** |
|
1057 Copies text from the specified descriptor and converts it to upper case before |
|
1058 putting it into this descriptor, replacing any existing data. |
|
1059 |
|
1060 The length of this descriptor is set to reflect the new data. |
|
1061 |
|
1062 Conversion to upper case is implemented as appropriate to the current locale. |
|
1063 |
|
1064 This leaving variant of the standard, non-leaving descriptor method |
|
1065 differs in that this operation may cause the string descriptor's heap |
|
1066 buffer to be reallocated in order to accommodate the new data. As a |
|
1067 result, MaxLength() and Ptr() may return different values afterwards, |
|
1068 and any existing raw pointers to into the descriptor data may be |
|
1069 invalidated. |
|
1070 |
|
1071 @param aDes A 16-bit non modifiable descriptor. |
|
1072 |
|
1073 @leave KErrNoMemory if the underlying buffer needs to be |
|
1074 grown and there are insufficient resources to do so |
|
1075 */ |
|
1076 EXPORT_C void LString16::CopyUCL(const TDesC16& aDes) |
|
1077 { |
|
1078 ReserveL(aDes.Length()); |
|
1079 RBuf16::CopyUC(aDes); |
|
1080 } |
|
1081 |
|
1082 /** |
|
1083 Copies text from the specified descriptor and capitalises it before putting |
|
1084 it into this descriptor, replacing any existing data. |
|
1085 |
|
1086 The length of this descriptor is set to reflect the new data. |
|
1087 |
|
1088 Capitalisation is implemented as appropriate to the current locale. |
|
1089 |
|
1090 This leaving variant of the standard, non-leaving descriptor method |
|
1091 differs in that this operation may cause the string descriptor's heap |
|
1092 buffer to be reallocated in order to accommodate the new data. As a |
|
1093 result, MaxLength() and Ptr() may return different values afterwards, |
|
1094 and any existing raw pointers to into the descriptor data may be |
|
1095 invalidated. |
|
1096 |
|
1097 @param aDes A 16-bit non-modifiable descriptor. |
|
1098 |
|
1099 @leave KErrNoMemory if the underlying buffer needs to be |
|
1100 grown and there are insufficient resources to do so |
|
1101 */ |
|
1102 EXPORT_C void LString16::CopyCPL(const TDesC16& aDes) |
|
1103 { |
|
1104 ReserveL(aDes.Length()); |
|
1105 RBuf16::CopyCP(aDes); |
|
1106 } |
|
1107 |
|
1108 /** |
|
1109 Appends and fills this descriptor with the specified character. |
|
1110 |
|
1111 The descriptor is appended with the specified number of characters. |
|
1112 and its length is changed to reflect this. |
|
1113 |
|
1114 This leaving variant of the standard, non-leaving descriptor method |
|
1115 differs in that this operation may cause the string descriptor's heap |
|
1116 buffer to be reallocated in order to accommodate the new data. As a |
|
1117 result, MaxLength() and Ptr() may return different values afterwards, |
|
1118 and any existing raw pointers to into the descriptor data may be |
|
1119 invalidated. |
|
1120 |
|
1121 @param aChar The fill character. |
|
1122 @param aLength The number of fill characters to be appended. |
|
1123 |
|
1124 @leave KErrNoMemory if the underlying buffer needs to be |
|
1125 grown and there are insufficient resources to do so |
|
1126 |
|
1127 @panic USER 11 if aLength is negative |
|
1128 */ |
|
1129 EXPORT_C void LString16::AppendFillL(TChar aChar,TInt aLength) |
|
1130 { |
|
1131 ReserveFreeCapacityGrowExponentialL(aLength); |
|
1132 RBuf16::AppendFill(aChar, aLength); |
|
1133 } |
|
1134 |
|
1135 /** |
|
1136 Appends a zero terminator onto the end of this descriptor's data. |
|
1137 |
|
1138 The length of the descriptor is not changed, but the capacity of the |
|
1139 descriptor may need to be grown to accommodate the zero terminator. |
|
1140 |
|
1141 This leaving variant of the standard, non-leaving descriptor method |
|
1142 differs in that this operation may cause the string descriptor's heap |
|
1143 buffer to be reallocated in order to accommodate the new data. As a |
|
1144 result, MaxLength() and Ptr() may return different values afterwards, |
|
1145 and any existing raw pointers to into the descriptor data may be |
|
1146 invalidated. |
|
1147 |
|
1148 @leave KErrNoMemory if the underlying buffer needs to be |
|
1149 grown and there are insufficient resources to do so |
|
1150 */ |
|
1151 EXPORT_C void LString16::ZeroTerminateL() |
|
1152 { |
|
1153 ReserveFreeCapacityL(1); |
|
1154 RBuf16::ZeroTerminate(); |
|
1155 } |
|
1156 |
|
1157 /** |
|
1158 Swaps the data represented by this descriptor with the data represented by |
|
1159 the specified descriptor. |
|
1160 |
|
1161 The lengths of both descriptors are also swapped to reflect the change. |
|
1162 |
|
1163 Note that each descriptor must be capable of accommodating the contents of |
|
1164 the other descriptor. |
|
1165 |
|
1166 Each descriptor must be capable of accommodating the contents of the |
|
1167 other descriptor. If the maximum length of the descriptor parameter is |
|
1168 smaller than the length of the target LString16, then the function |
|
1169 raises a USER 11 panic. The target LString16 will be grown if |
|
1170 necessary to accommodate the descriptor parameter's data. |
|
1171 |
|
1172 This leaving variant of the standard, non-leaving descriptor method |
|
1173 differs in that this operation may cause the string descriptor's heap |
|
1174 buffer to be reallocated in order to accommodate the new data. As a |
|
1175 result, MaxLength() and Ptr() may return different values afterwards, |
|
1176 and any existing raw pointers to into the descriptor data may be |
|
1177 invalidated. |
|
1178 |
|
1179 @param aDes The 16-bit modifiable descriptor whose data is to be swapped with |
|
1180 the data of this descriptor. |
|
1181 |
|
1182 @leave KErrNoMemory if the underlying buffer needs to be |
|
1183 grown and there are insufficient resources to do so |
|
1184 |
|
1185 @panic USER 11 if the maximum length of the descriptor parameter is smaller than the |
|
1186 length of the target LString16 |
|
1187 */ |
|
1188 EXPORT_C void LString16::SwapL(TDes16& aDes) |
|
1189 { |
|
1190 ReserveL(aDes.Length()); |
|
1191 TDes16::Swap(aDes); |
|
1192 } |
|
1193 |
|
1194 /** |
|
1195 Swaps the data represented by this string descriptor with the data |
|
1196 represented by the specified string descriptor. |
|
1197 |
|
1198 The lengths of both string descriptors are also swapped to reflect the |
|
1199 change, and their buffers grown as necessary to accommodate the data |
|
1200 they receive. |
|
1201 |
|
1202 This leaving variant of the standard, non-leaving descriptor method |
|
1203 differs in that this operation may cause the string descriptor's heap |
|
1204 buffer to be reallocated in order to accommodate the new data. As a |
|
1205 result, MaxLength() and Ptr() may return different values afterwards, |
|
1206 and any existing raw pointers to into the descriptor data may be |
|
1207 invalidated. |
|
1208 |
|
1209 @param aDes The 16-bit modifiable string descriptor whose data is to be swapped with |
|
1210 the data of this descriptor. |
|
1211 |
|
1212 @leave KErrNoMemory if one of the underlying buffers needs to be |
|
1213 grown and there are insufficient resources to do so |
|
1214 */ |
|
1215 EXPORT_C void LString16::SwapL(LString16& aDes) |
|
1216 { |
|
1217 this->ReserveL(aDes.Length()); |
|
1218 aDes.ReserveL(this->Length()); |
|
1219 TDes16::Swap(aDes); |
|
1220 } |
|
1221 |
|
1222 |
|
1223 /** |
|
1224 Inserts data into this descriptor. |
|
1225 |
|
1226 The length of this descriptor is changed to reflect the extra data. |
|
1227 |
|
1228 This leaving variant of the standard, non-leaving descriptor method |
|
1229 differs in that this operation may cause the string descriptor's heap |
|
1230 buffer to be reallocated in order to accommodate the new data. As a |
|
1231 result, MaxLength() and Ptr() may return different values afterwards, |
|
1232 and any existing raw pointers to into the descriptor data may be |
|
1233 invalidated. |
|
1234 |
|
1235 @param aPos The position within the data where insertion is to start. This |
|
1236 is an offset value; a zero value refers to the leftmost data |
|
1237 position. |
|
1238 |
|
1239 @param aDes A 16-bit non modifiable descriptor whose data is to be inserted. |
|
1240 |
|
1241 @leave KErrNoMemory if the underlying buffer needs to be |
|
1242 grown and there are insufficient resources to do so |
|
1243 |
|
1244 @panic USER 10 if aPos is negative or is greater than the length of this |
|
1245 descriptor. |
|
1246 */ |
|
1247 EXPORT_C void LString16::InsertL(TInt aPos,const TDesC16& aDes) |
|
1248 { |
|
1249 ReserveFreeCapacityGrowExponentialL(aDes.Length()); |
|
1250 RBuf16::Insert(aPos, aDes); |
|
1251 } |
|
1252 |
|
1253 /** |
|
1254 Replaces data in this descriptor. |
|
1255 |
|
1256 The specified length can be different to the length of the replacement data. |
|
1257 The length of this descriptor changes to reflect the change of data. |
|
1258 |
|
1259 This leaving variant of the standard, non-leaving descriptor method |
|
1260 differs in that this operation may cause the string descriptor's heap |
|
1261 buffer to be reallocated in order to accommodate the new data. As a |
|
1262 result, MaxLength() and Ptr() may return different values afterwards, |
|
1263 and any existing raw pointers to into the descriptor data may be |
|
1264 invalidated. |
|
1265 |
|
1266 @param aPos The position within the data where replacement is to start. |
|
1267 This is an offset value; a zero value refers to the leftmost |
|
1268 data position. |
|
1269 |
|
1270 @param aLength The length of data to be replaced. |
|
1271 |
|
1272 @param aDes The source 16-bit non modifiable descriptor whose data is to |
|
1273 replace the target descriptor's data at aPos. |
|
1274 |
|
1275 @leave KErrNoMemory if the underlying buffer needs to be |
|
1276 grown and there are insufficient resources to do so |
|
1277 |
|
1278 @panic USER 8 if aLength is negative |
|
1279 |
|
1280 @panic USER 10 if aPos is negative or is greater than the length of this |
|
1281 descriptor. |
|
1282 |
|
1283 @panic USER 16 if the length of the source descriptor aDes is negative |
|
1284 */ |
|
1285 EXPORT_C void LString16::ReplaceL(TInt aPos,TInt aLength,const TDesC16& aDes) |
|
1286 { |
|
1287 TInt delta = aDes.Length() - aLength; |
|
1288 if (delta > 0) |
|
1289 { |
|
1290 ReserveFreeCapacityGrowExponentialL(delta); |
|
1291 } |
|
1292 RBuf16::Replace(aPos, aLength, aDes); |
|
1293 } |
|
1294 |
|
1295 /** |
|
1296 Copies data into this descriptor and justifies it, replacing any existing data. |
|
1297 |
|
1298 The length of this descriptor is set to reflect the new data. |
|
1299 |
|
1300 The target area is considered to be an area of specified width positioned at |
|
1301 the beginning of this descriptor's data area. Source data is copied into, and |
|
1302 aligned within this target area according to the specified alignment |
|
1303 instruction. |
|
1304 |
|
1305 If the length of the target area is larger than the length of the source, then |
|
1306 spare space within the target area is padded with the fill character. |
|
1307 |
|
1308 This leaving variant of the standard, non-leaving descriptor method |
|
1309 differs in that this operation may cause the string descriptor's heap |
|
1310 buffer to be reallocated in order to accommodate the new data. As a |
|
1311 result, MaxLength() and Ptr() may return different values afterwards, |
|
1312 and any existing raw pointers to into the descriptor data may be |
|
1313 invalidated. |
|
1314 |
|
1315 @param aDes A 16-bit non-modifiable descriptor containing the source data. |
|
1316 The length of the data to be copied is the smaller of: |
|
1317 the length of the source descriptor, and |
|
1318 the width of the target area (only if this is not the |
|
1319 explicit negative value KDefaultJustifyWidth). |
|
1320 |
|
1321 @param aWidth The width of the target area. If this has the specific |
|
1322 negative value KDefaultJustifyWidth, then the width is |
|
1323 re-set to the length of the data source. |
|
1324 |
|
1325 @param aAlignment The alignment of the data within the target area |
|
1326 |
|
1327 @param aFill The fill character used to pad the target area. |
|
1328 |
|
1329 @leave KErrNoMemory if the underlying buffer needs to be |
|
1330 grown and there are insufficient resources to do so |
|
1331 |
|
1332 @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. |
|
1333 */ |
|
1334 EXPORT_C void LString16::JustifyL(const TDesC16& aDes,TInt aWidth,TAlign aAlignment,TChar aFill) |
|
1335 { |
|
1336 TInt width = (aWidth == KDefaultJustifyWidth ? aDes.Length() : aWidth); |
|
1337 ReserveL(width); |
|
1338 RBuf16::Justify(aDes, aWidth, aAlignment, aFill); |
|
1339 } |
|
1340 |
|
1341 /** |
|
1342 Converts the specified unsigned integer into a fixed width character |
|
1343 representation based on the specified number system and copies the conversion |
|
1344 into this descriptor, replacing any existing data. |
|
1345 |
|
1346 The length of this descriptor is set to reflect the new data. |
|
1347 |
|
1348 The function generates the exact number of specified characters, either padding |
|
1349 to the left with character zeroes or discarding low order characters as |
|
1350 necessary. |
|
1351 |
|
1352 When a hexadecimal conversion is specified, hexadecimal characters are in |
|
1353 upper case. |
|
1354 |
|
1355 This function is equivalent to using Format() with parameters which specify: |
|
1356 |
|
1357 1. a fixed length target field |
|
1358 |
|
1359 2. padding with zero characters, for example "%08x". |
|
1360 |
|
1361 When this is the case, always use NumFixedWidthUC() in |
|
1362 preference to Format() as it is more efficient. |
|
1363 |
|
1364 This leaving variant of the standard, non-leaving descriptor method |
|
1365 differs in that this operation may cause the string descriptor's heap |
|
1366 buffer to be reallocated in order to accommodate the new data. As a |
|
1367 result, MaxLength() and Ptr() may return different values afterwards, |
|
1368 and any existing raw pointers to into the descriptor data may be |
|
1369 invalidated. |
|
1370 |
|
1371 @param aVal The unsigned integer value. |
|
1372 @param aRadix The number system representation for the unsigned integer. |
|
1373 @param aWidth The number of characters: to be used to contain the conversion, |
|
1374 to be copied into this descriptor. |
|
1375 |
|
1376 @leave KErrNoMemory if the underlying buffer needs to be |
|
1377 grown and there are insufficient resources to do so |
|
1378 |
|
1379 @see TDes16::Format() |
|
1380 */ |
|
1381 EXPORT_C void LString16::NumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth) |
|
1382 { |
|
1383 Zero(); |
|
1384 AppendNumFixedWidthUCL(aVal, aRadix, aWidth); |
|
1385 } |
|
1386 |
|
1387 /** |
|
1388 Converts the specified 64 bit unsigned integer into a character representation |
|
1389 based on the specified number system and copies the conversion into this |
|
1390 descriptor, replacing any existing data. |
|
1391 |
|
1392 The length of this descriptor is set to reflect the new data. |
|
1393 |
|
1394 When a hexadecimal conversion is specified, hexadecimal characters are in |
|
1395 upper case. |
|
1396 |
|
1397 This leaving variant of the standard, non-leaving descriptor method |
|
1398 differs in that this operation may cause the string descriptor's heap |
|
1399 buffer to be reallocated in order to accommodate the new data. As a |
|
1400 result, MaxLength() and Ptr() may return different values afterwards, |
|
1401 and any existing raw pointers to into the descriptor data may be |
|
1402 invalidated. |
|
1403 |
|
1404 @param aVal The 64 bit integer value. This is always treated as an unsigned |
|
1405 value for all builds. |
|
1406 @param aRadix The number system representation for the 64 bit integer. If no |
|
1407 explicit value is specified, then EDecimal is the default. |
|
1408 |
|
1409 @leave KErrNoMemory if the underlying buffer needs to be |
|
1410 grown and there are insufficient resources to do so |
|
1411 */ |
|
1412 EXPORT_C void LString16::NumUCL(TUint64 aVal, TRadix aRadix) |
|
1413 { |
|
1414 Zero(); |
|
1415 AppendNumUCL(aVal, aRadix); |
|
1416 } |
|
1417 |
|
1418 /** |
|
1419 Converts the specified floating point number into a character representation |
|
1420 and copies the conversion into this descriptor, replacing any existing data. |
|
1421 |
|
1422 The length of this descriptor is set to reflect the new data. |
|
1423 |
|
1424 The character representation of the real number is dictated by the specified |
|
1425 format. |
|
1426 |
|
1427 Note that the function leaves if the iType data member of the specified |
|
1428 TRealFormat object has both an invalid character representation format |
|
1429 (i.e. the format type) and invalid format flags. |
|
1430 |
|
1431 This leaving variant of the standard, non-leaving descriptor method |
|
1432 differs in that this operation may cause the string descriptor's heap |
|
1433 buffer to be reallocated in order to accommodate the new data. As a |
|
1434 result, MaxLength() and Ptr() may return different values afterwards, |
|
1435 and any existing raw pointers to into the descriptor data may be |
|
1436 invalidated. |
|
1437 |
|
1438 @param aVal The floating point number to be converted. |
|
1439 @param aFormat The format of the conversion. |
|
1440 |
|
1441 @return If the conversion is successful, the length of this descriptor. If |
|
1442 the conversion fails, a negative value indicating the cause of failure. |
|
1443 In addition, extra information on the cause of the failure may be |
|
1444 appended onto this descriptor. The possible values and their meaning |
|
1445 are: |
|
1446 |
|
1447 1.KErrArgument - the supplied floating point number is not a valid |
|
1448 number. The three characters NaN are appended to this descriptor. |
|
1449 |
|
1450 2.KErrOverflow - the number is too large to represent. |
|
1451 2.1 For positive overflow, the three characters Inf are appended |
|
1452 to this descriptor. |
|
1453 2.2 For negative overflow, the four characters -Inf are appended |
|
1454 to this descriptor. |
|
1455 |
|
1456 3.KErrUnderflow - the number is too small to represent. |
|
1457 3.1 For positive underflow, the three characters Inf are appended |
|
1458 to this descriptor. |
|
1459 3.2 For negative underflow, the four characters -Inf are appended |
|
1460 to this descriptor. |
|
1461 |
|
1462 4.KErrGeneral - the conversion cannot be completed. There are a |
|
1463 number of possible reasons for this, but the most common is: |
|
1464 4.1 The character representation format (i.e. the format type), as |
|
1465 defined in the TRealFormat object is not recognised. |
|
1466 |
|
1467 @leave KErrNoMemory if the underlying buffer needs to be |
|
1468 grown and there are insufficient resources to do so |
|
1469 |
|
1470 @see TRealFormat::iType |
|
1471 */ |
|
1472 EXPORT_C TInt LString16::NumL(TReal aVal,const TRealFormat &aFormat) |
|
1473 { |
|
1474 Zero(); |
|
1475 return AppendNumL(aVal, aFormat); |
|
1476 } |
|
1477 |
|
1478 /** |
|
1479 Converts the 64-bit signed integer into a decimal character representation |
|
1480 and copies the conversion into this descriptor, replacing any existing data. |
|
1481 |
|
1482 The length of this descriptor is set to reflect the new data. |
|
1483 |
|
1484 If the integer is negative, the character representation is prefixed by a |
|
1485 minus sign. |
|
1486 |
|
1487 This leaving variant of the standard, non-leaving descriptor method |
|
1488 differs in that this operation may cause the string descriptor's heap |
|
1489 buffer to be reallocated in order to accommodate the new data. As a |
|
1490 result, MaxLength() and Ptr() may return different values afterwards, |
|
1491 and any existing raw pointers to into the descriptor data may be |
|
1492 invalidated. |
|
1493 |
|
1494 @param aVal The 64-bit signed integer value. |
|
1495 |
|
1496 @leave KErrNoMemory if the underlying buffer needs to be |
|
1497 grown and there are insufficient resources to do so |
|
1498 */ |
|
1499 EXPORT_C void LString16::NumL(TInt64 aVal) |
|
1500 { |
|
1501 Zero(); |
|
1502 AppendNumL(aVal); |
|
1503 } |
|
1504 |
|
1505 /** |
|
1506 Converts the specified 64 bit unsigned integer into a character representation |
|
1507 based on the specified number system and copies the conversion into this |
|
1508 descriptor, replacing any existing data. |
|
1509 |
|
1510 The length of this descriptor is set to reflect the new data. |
|
1511 |
|
1512 When a hexadecimal conversion is specified, hexadecimal characters are in |
|
1513 lower case. |
|
1514 |
|
1515 This leaving variant of the standard, non-leaving descriptor method |
|
1516 differs in that this operation may cause the string descriptor's heap |
|
1517 buffer to be reallocated in order to accommodate the new data. As a |
|
1518 result, MaxLength() and Ptr() may return different values afterwards, |
|
1519 and any existing raw pointers to into the descriptor data may be |
|
1520 invalidated. |
|
1521 |
|
1522 @param aVal The 64 bit integer value. This is treated as an unsigned |
|
1523 value for all builds. |
|
1524 @param aRadix The number system representation for the 64 bit integer. |
|
1525 |
|
1526 @leave KErrNoMemory if the underlying buffer needs to be |
|
1527 grown and there are insufficient resources to do so |
|
1528 */ |
|
1529 EXPORT_C void LString16::NumL(TUint64 aVal, TRadix aRadix) |
|
1530 { |
|
1531 Zero(); |
|
1532 AppendNumL(aVal, aRadix); |
|
1533 } |
|
1534 |
|
1535 /** |
|
1536 Formats and copies text into this descriptor, replacing any existing data. |
|
1537 |
|
1538 The length of this descriptor is set to reflect the new data. |
|
1539 |
|
1540 The function takes a format string and a variable number of arguments. |
|
1541 The format string contains literal text embedded with directives for converting |
|
1542 the trailing list of arguments into text. |
|
1543 |
|
1544 The embedded directives are character sequences prefixed with the '%' character. |
|
1545 The literal text is simply copied into this descriptor unaltered while |
|
1546 the '%' directives are used to convert successive arguments from the |
|
1547 trailing list. |
|
1548 |
|
1549 The resulting stream of literal text and converted arguments is copied into |
|
1550 this descriptor. |
|
1551 |
|
1552 The syntax of the embedded directives follows one of four general patterns. |
|
1553 |
|
1554 Note that formatting of single numerical values can be achieved more |
|
1555 conveniently using the Num() and NumUC() member functions of this class. |
|
1556 |
|
1557 The full description of the syntax of a format string cannot be included here. |
|
1558 For full details, navigate to the Symbian OS guide, and follow the hierarchy of links: |
|
1559 |
|
1560 @code |
|
1561 Symbian OS Guide |
|
1562 Base |
|
1563 Using User Library (E32) |
|
1564 Buffers and Strings |
|
1565 Using Descriptors |
|
1566 How to Use Descriptors |
|
1567 Format string syntax |
|
1568 @endcode |
|
1569 |
|
1570 This leaving variant of the standard, non-leaving descriptor method |
|
1571 differs in that this operation may cause the string descriptor's heap |
|
1572 buffer to be reallocated in order to accommodate the new data. As a |
|
1573 result, MaxLength() and Ptr() may return different values afterwards, |
|
1574 and any existing raw pointers to into the descriptor data may be |
|
1575 invalidated. |
|
1576 |
|
1577 @param aFmt The descriptor containing the format string. |
|
1578 The TRefByValue class provides a constructor which takes a |
|
1579 TDesC8 type. |
|
1580 |
|
1581 @param ... A variable number of arguments to be converted to text as |
|
1582 dictated by the format string. |
|
1583 |
|
1584 @panic USER 12 if the format string has incorrect syntax. |
|
1585 |
|
1586 @leave KErrNoMemory if the underlying buffer needs to be |
|
1587 grown and there are insufficient resources to do so |
|
1588 |
|
1589 @see TDes16::Num() |
|
1590 @see TDes16::NumUC() |
|
1591 */ |
|
1592 EXPORT_C void LString16::FormatL(TRefByValue<const TDesC16> aFmt,...) |
|
1593 { |
|
1594 VA_LIST list; |
|
1595 VA_START(list,aFmt); |
|
1596 FormatListL(aFmt,list); |
|
1597 } |
|
1598 |
|
1599 /** |
|
1600 Formats and copies text into this descriptor, replacing any existing data. |
|
1601 |
|
1602 The length of this descriptor is set to reflect the new data. |
|
1603 |
|
1604 The behaviour of this function is the same as FormatL(). In practice, it is |
|
1605 better and easier to use FormatL(), passing a variable number of arguments |
|
1606 as required by the format string. |
|
1607 |
|
1608 This leaving variant of the standard, non-leaving descriptor method |
|
1609 differs in that this operation may cause the string descriptor's heap |
|
1610 buffer to be reallocated in order to accommodate the new data. As a |
|
1611 result, MaxLength() and Ptr() may return different values afterwards, |
|
1612 and any existing raw pointers to into the descriptor data may be |
|
1613 invalidated. |
|
1614 |
|
1615 @param aFmt The descriptor containing the format string. |
|
1616 @param aList A pointer to an argument list. |
|
1617 |
|
1618 @leave KErrNoMemory if the underlying buffer needs to be |
|
1619 grown and there are insufficient resources to do so |
|
1620 |
|
1621 @see TDes16::Format() |
|
1622 @see VA_LIST |
|
1623 */ |
|
1624 EXPORT_C void LString16::FormatListL(const TDesC16& aFmt,VA_LIST aList) |
|
1625 { |
|
1626 Zero(); |
|
1627 AppendFormatListL(aFmt, aList); |
|
1628 } |
|
1629 |
|
1630 /** |
|
1631 Appends data onto the end of this descriptor's data and justifies it. |
|
1632 |
|
1633 The source of the appended data is an existing descriptor. |
|
1634 |
|
1635 The target area is considered to be an area of specified width, immediately |
|
1636 following this descriptor's existing data. Source data is copied into, and |
|
1637 aligned within this target area according to the specified alignment instruction. |
|
1638 |
|
1639 If the length of the target area is larger than the length of the source, |
|
1640 then spare space within the target area is padded with the fill character. |
|
1641 |
|
1642 This leaving variant of the standard, non-leaving descriptor method |
|
1643 differs in that this operation may cause the string descriptor's heap |
|
1644 buffer to be reallocated in order to accommodate the new data. As a |
|
1645 result, MaxLength() and Ptr() may return different values afterwards, |
|
1646 and any existing raw pointers to into the descriptor data may be |
|
1647 invalidated. |
|
1648 |
|
1649 @param aDes A 16-bit non-modifiable descriptor containing the source |
|
1650 data. The length of the data to be copied is the smaller of: |
|
1651 the length of the source descriptor, and |
|
1652 the width of the target area (only if this is not the |
|
1653 explicit negative value KDefaultJustifyWidth). |
|
1654 |
|
1655 @param aWidth The width of the target area. If this has the specific |
|
1656 negative value KDefaultJustifyWidth, then the width is |
|
1657 re-set to the length of the data source. |
|
1658 |
|
1659 @param aAlignment The alignment of the data within the target area. |
|
1660 |
|
1661 @param aFill The fill character used to pad the target area. |
|
1662 |
|
1663 @leave KErrNoMemory if the underlying buffer needs to be |
|
1664 grown and there are insufficient resources to do so |
|
1665 |
|
1666 @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. |
|
1667 */ |
|
1668 EXPORT_C void LString16::AppendJustifyL(const TDesC16& Des,TInt aWidth,TAlign aAlignment,TChar aFill) |
|
1669 { |
|
1670 |
|
1671 TInt width = (aWidth == KDefaultJustifyWidth ? Des.Length() : aWidth); |
|
1672 ReserveFreeCapacityGrowExponentialL(width); |
|
1673 RBuf16::AppendJustify(Des, aWidth, aAlignment, aFill); |
|
1674 } |
|
1675 |
|
1676 /** |
|
1677 Appends data onto the end of this descriptor's data and justifies it. |
|
1678 |
|
1679 The source of the appended data is an existing descriptor. |
|
1680 |
|
1681 The target area is considered to be an area of specified width, immediately |
|
1682 following this descriptor's existing data. Source data is copied into, and |
|
1683 aligned within this target area according to the specified alignment instruction. |
|
1684 |
|
1685 If the length of the target area is larger than the length of the source, |
|
1686 then spare space within the target area is padded with the fill character. |
|
1687 |
|
1688 This leaving variant of the standard, non-leaving descriptor method |
|
1689 differs in that this operation may cause the string descriptor's heap |
|
1690 buffer to be reallocated in order to accommodate the new data. As a |
|
1691 result, MaxLength() and Ptr() may return different values afterwards, |
|
1692 and any existing raw pointers to into the descriptor data may be |
|
1693 invalidated. |
|
1694 |
|
1695 @param aDes An 8-bit non-modifiable descriptor containing the source data. |
|
1696 |
|
1697 @param aLength The length of data to be copied from the source descriptor. |
|
1698 If this is greater than the width of the target area, then |
|
1699 the length of data copied is limited to the width. |
|
1700 The length of data to be copied must not be greater than |
|
1701 the length of the source descriptor. Note that this |
|
1702 condition is not automatically tested. |
|
1703 |
|
1704 @param aWidth The width of the target area. If this has the specific negative |
|
1705 value KDefaultJustifyWidth, then the width is |
|
1706 re-set to the length of the data source. |
|
1707 |
|
1708 @param aAlignment The alignment of the data within the target area. |
|
1709 |
|
1710 @param aFill The fill character used to pad the target area. |
|
1711 |
|
1712 @leave KErrNoMemory if the underlying buffer needs to be |
|
1713 grown and there are insufficient resources to do so |
|
1714 |
|
1715 @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. |
|
1716 */ |
|
1717 EXPORT_C void LString16::AppendJustifyL(const TDesC16& Des,TInt aLength,TInt aWidth,TAlign aAlignment,TChar aFill) |
|
1718 { |
|
1719 |
|
1720 TInt width = (aWidth == KDefaultJustifyWidth ? aLength : aWidth); |
|
1721 ReserveFreeCapacityGrowExponentialL(width); |
|
1722 |
|
1723 RBuf16::AppendJustify(Des, aLength, aWidth, aAlignment, aFill); |
|
1724 } |
|
1725 |
|
1726 /** |
|
1727 Appends a zero terminated string onto the end of this descriptor's data and |
|
1728 justifies it. |
|
1729 |
|
1730 The zero terminator is not copied. |
|
1731 |
|
1732 The target area is considered to be an area of specified width, immediately |
|
1733 following this descriptor's existing data. Source data is copied into, and |
|
1734 aligned within, this target area according to the specified alignment instruction. |
|
1735 |
|
1736 If the length of the target area is larger than the length of the source, |
|
1737 then spare space within the target area is padded with the fill character. |
|
1738 |
|
1739 This leaving variant of the standard, non-leaving descriptor method |
|
1740 differs in that this operation may cause the string descriptor's heap |
|
1741 buffer to be reallocated in order to accommodate the new data. As a |
|
1742 result, MaxLength() and Ptr() may return different values afterwards, |
|
1743 and any existing raw pointers to into the descriptor data may be |
|
1744 invalidated. |
|
1745 |
|
1746 @param aZeroTerminatedString A pointer to a zero terminated string The length of the data |
|
1747 to be copied is the smaller of: the length of the string (excluding the zero |
|
1748 terminator), the width of the target area (only if this is not the explicit |
|
1749 negative value KDefaultJustifyWidth). |
|
1750 |
|
1751 @param aWidth The width of the target area. If this has the specific negative |
|
1752 value KDefaultJustifyWidth, then the width is re-set to the length of the |
|
1753 zero terminated string (excluding the zero terminator). |
|
1754 |
|
1755 @param aAlignment The alignment of the data within the target area. |
|
1756 |
|
1757 @param aFill The fill character used to pad the target area. |
|
1758 |
|
1759 @leave KErrNoMemory if the underlying buffer needs to be |
|
1760 grown and there are insufficient resources to do so |
|
1761 |
|
1762 @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. |
|
1763 */ |
|
1764 EXPORT_C void LString16::AppendJustifyL(const TUint16* aZeroTerminatedString,TInt aWidth,TAlign aAlignment,TChar aFill) |
|
1765 { |
|
1766 |
|
1767 TInt width = (aWidth == KDefaultJustifyWidth ? User::StringLength(aZeroTerminatedString) : aWidth); |
|
1768 ReserveFreeCapacityGrowExponentialL(width); |
|
1769 |
|
1770 RBuf16::AppendJustify(aZeroTerminatedString, aWidth, aAlignment, aFill); |
|
1771 |
|
1772 } |
|
1773 |
|
1774 /** |
|
1775 Appends data onto the end of this descriptor's data and justifies it. |
|
1776 |
|
1777 The source of the appended data is a memory location. |
|
1778 |
|
1779 The target area is considered to be an area of specified width, immediately |
|
1780 following this descriptor's existing data. Source data is copied into, and |
|
1781 aligned within, this target area according to the specified alignment instruction. |
|
1782 |
|
1783 If the length of the target area is larger than the length of the source, |
|
1784 then spare space within the target area is padded with the fill character. |
|
1785 |
|
1786 This leaving variant of the standard, non-leaving descriptor method |
|
1787 differs in that this operation may cause the string descriptor's heap |
|
1788 buffer to be reallocated in order to accommodate the new data. As a |
|
1789 result, MaxLength() and Ptr() may return different values afterwards, |
|
1790 and any existing raw pointers to into the descriptor data may be |
|
1791 invalidated. |
|
1792 |
|
1793 @param aString A pointer to a source memory location. |
|
1794 |
|
1795 @param aLength The length of data to be copied. If this is greater than the |
|
1796 width of the target area, then the length of data copied is |
|
1797 limited to the width. |
|
1798 |
|
1799 @param aWidth The width of the target area. If this has the specific negative |
|
1800 value KDefaultJustifyWidth, then the width is |
|
1801 re-set to the length of the data source. |
|
1802 |
|
1803 @param aAlignment The alignment of the data within the target area. |
|
1804 |
|
1805 @param aFill The fill character used to pad the target area. |
|
1806 |
|
1807 @leave KErrNoMemory if the underlying buffer needs to be |
|
1808 grown and there are insufficient resources to do so |
|
1809 |
|
1810 @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. |
|
1811 |
|
1812 @panic USER 17 if aLength is negative. |
|
1813 */ |
|
1814 EXPORT_C void LString16::AppendJustifyL(const TUint16* aString,TInt aLength,TInt aWidth,TAlign aAlignment,TChar aFill) |
|
1815 { |
|
1816 |
|
1817 TInt width = (aWidth == KDefaultJustifyWidth ? aLength : aWidth); |
|
1818 ReserveFreeCapacityGrowExponentialL(width); |
|
1819 |
|
1820 RBuf16::AppendJustify(aString, aLength, aWidth, aAlignment, aFill); |
|
1821 } |
|
1822 |
|
1823 /** |
|
1824 Converts the specified unsigned integer into a fixed width character |
|
1825 representation based on the specified number system and appends the conversion |
|
1826 onto the end of this descriptor's data. |
|
1827 |
|
1828 The length of this descriptor is incremented to reflect the new content. |
|
1829 |
|
1830 The function generates the exact number of specified characters, either |
|
1831 padding to the left with character zeroes or discarding low order characters |
|
1832 as necessary. |
|
1833 |
|
1834 When a hexadecimal conversion is specified, hexadecimal characters are in |
|
1835 upper case. |
|
1836 |
|
1837 This leaving variant of the standard, non-leaving descriptor method |
|
1838 differs in that this operation may cause the string descriptor's heap |
|
1839 buffer to be reallocated in order to accommodate the new data. As a |
|
1840 result, MaxLength() and Ptr() may return different values afterwards, |
|
1841 and any existing raw pointers to into the descriptor data may be |
|
1842 invalidated. |
|
1843 |
|
1844 @param aVal The unsigned integer value. |
|
1845 @param aRadix The number system representation for the unsigned integer. |
|
1846 @param aWidth The number of characters: to be used to contain the conversion, |
|
1847 to be appended to this descriptor. |
|
1848 |
|
1849 @leave KErrNoMemory if the underlying buffer needs to be |
|
1850 grown and there are insufficient resources to do so |
|
1851 |
|
1852 */ |
|
1853 EXPORT_C void LString16::AppendNumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth) |
|
1854 { |
|
1855 ReserveFreeCapacityGrowExponentialL(aWidth); |
|
1856 RBuf16::AppendNumFixedWidthUC(aVal, aRadix, aWidth); |
|
1857 } |
|
1858 |
|
1859 /** |
|
1860 Converts the specified 64 bit integer into a character representation |
|
1861 based on the specified number system and appends the conversion onto the end |
|
1862 of this descriptor's data. |
|
1863 |
|
1864 The length of this descriptor is incremented to reflect the new content. |
|
1865 |
|
1866 When a hexadecimal conversion is specified, hexadecimal characters are in |
|
1867 upper case. |
|
1868 |
|
1869 This leaving variant of the standard, non-leaving descriptor method |
|
1870 differs in that this operation may cause the string descriptor's heap |
|
1871 buffer to be reallocated in order to accommodate the new data. As a |
|
1872 result, MaxLength() and Ptr() may return different values afterwards, |
|
1873 and any existing raw pointers to into the descriptor data may be |
|
1874 invalidated. |
|
1875 |
|
1876 @param aVal The 64 bit integer value. This is always treated as an unsigned |
|
1877 value. |
|
1878 @param aRadix The number system representation for the 64 bit integer. If no |
|
1879 explicit value is specified, then EDecimal is the default. |
|
1880 |
|
1881 @leave KErrNoMemory if the underlying buffer needs to be |
|
1882 grown and there are insufficient resources to do so |
|
1883 */ |
|
1884 EXPORT_C void LString16::AppendNumUCL(TUint64 aVal, TRadix aRadix) |
|
1885 { |
|
1886 ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize); |
|
1887 RBuf16::AppendNumUC(aVal, aRadix); |
|
1888 } |
|
1889 |
|
1890 /** |
|
1891 Converts the specified floating point number into a character representation |
|
1892 and appends the conversion onto the end of this descriptor's data. |
|
1893 |
|
1894 The length of this descriptor is incremented to reflect the new content. |
|
1895 |
|
1896 The character representation of the real number is dictated by the specified |
|
1897 format. |
|
1898 |
|
1899 This leaving variant of the standard, non-leaving descriptor method |
|
1900 differs in that this operation may cause the string descriptor's heap |
|
1901 buffer to be reallocated in order to accommodate the new data. As a |
|
1902 result, MaxLength() and Ptr() may return different values afterwards, |
|
1903 and any existing raw pointers to into the descriptor data may be |
|
1904 invalidated. |
|
1905 |
|
1906 @param aVal The floating point number to be converted. |
|
1907 @param aFormat The format of the conversion. |
|
1908 |
|
1909 @return If the conversion is successful, the length of this descriptor. If |
|
1910 the conversion fails, a negative value indicating the cause of failure. |
|
1911 In addition, extra information on the cause of the failure may be |
|
1912 appended onto this descriptor. The possible values and their meaning |
|
1913 are: |
|
1914 |
|
1915 1.KErrArgument - the supplied floating point number is not a valid |
|
1916 number. The three characters NaN are appended to this descriptor. |
|
1917 |
|
1918 2.KErrOverflow - the number is too large to represent. |
|
1919 2.1 For positive overflow, the three characters Inf are appended |
|
1920 to this descriptor. |
|
1921 2.2 For negative overflow, the four characters -Inf are appended |
|
1922 to this descriptor. |
|
1923 |
|
1924 3.KErrUnderflow - the number is too small to represent. |
|
1925 3.1 For positive underflow, the three characters Inf are appended |
|
1926 to this descriptor. |
|
1927 3.2 For negative underflow, the four characters -Inf are appended |
|
1928 to this descriptor. |
|
1929 |
|
1930 4.KErrGeneral - the conversion cannot be completed. There are a |
|
1931 number of possible reasons for this, but the most common is: |
|
1932 4.1 The character representation format (i.e. the format type), as |
|
1933 defined in the TRealFormat object is not recognised. |
|
1934 |
|
1935 @leave KErrNoMemory if the underlying buffer needs to be |
|
1936 grown and there are insufficient resources to do so |
|
1937 */ |
|
1938 EXPORT_C TInt LString16::AppendNumL(TReal aVal,const TRealFormat& aFormat) |
|
1939 { |
|
1940 ReserveFreeCapacityGrowExponentialL(aFormat.iWidth + 1 + KDefaultExpandSize); |
|
1941 return RBuf16::AppendNum(aVal, aFormat); |
|
1942 } |
|
1943 |
|
1944 /** |
|
1945 Converts the 64-bit signed integer into a decimal character representation |
|
1946 and appends the conversion onto the end of this descriptor's data. |
|
1947 |
|
1948 The length of this descriptor is incremented to reflect the new content. |
|
1949 |
|
1950 If the integer is negative, the character representation is prefixed by a |
|
1951 minus sign. |
|
1952 |
|
1953 This leaving variant of the standard, non-leaving descriptor method |
|
1954 differs in that this operation may cause the string descriptor's heap |
|
1955 buffer to be reallocated in order to accommodate the new data. As a |
|
1956 result, MaxLength() and Ptr() may return different values afterwards, |
|
1957 and any existing raw pointers to into the descriptor data may be |
|
1958 invalidated. |
|
1959 |
|
1960 @param aVal The 64-bit signed integer value. |
|
1961 |
|
1962 @leave KErrNoMemory if the underlying buffer needs to be |
|
1963 grown and there are insufficient resources to do so |
|
1964 */ |
|
1965 EXPORT_C void LString16::AppendNumL(TInt64 aVal) |
|
1966 { |
|
1967 ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize); |
|
1968 RBuf16::AppendNum(aVal); |
|
1969 } |
|
1970 |
|
1971 /** |
|
1972 Converts the specified 64 bit integer into a character representation |
|
1973 based on the specified number system and appends the conversion onto the end |
|
1974 of this descriptor's data. |
|
1975 |
|
1976 The length of this descriptor is incremented to reflect the new content. |
|
1977 |
|
1978 When a hexadecimal conversion is specified, hexadecimal characters are in |
|
1979 lower case. |
|
1980 |
|
1981 This leaving variant of the standard, non-leaving descriptor method |
|
1982 differs in that this operation may cause the string descriptor's heap |
|
1983 buffer to be reallocated in order to accommodate the new data. As a |
|
1984 result, MaxLength() and Ptr() may return different values afterwards, |
|
1985 and any existing raw pointers to into the descriptor data may be |
|
1986 invalidated. |
|
1987 |
|
1988 @param aVal The 64 bit integer value. This is always treated as an unsigned |
|
1989 value. |
|
1990 @param aRadix The number system representation for the 64 bit integer. |
|
1991 |
|
1992 @leave KErrNoMemory if the underlying buffer needs to be |
|
1993 grown and there are insufficient resources to do so |
|
1994 */ |
|
1995 EXPORT_C void LString16::AppendNumL(TUint64 aVal, TRadix aRadix) |
|
1996 { |
|
1997 ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize); |
|
1998 RBuf16::AppendNum(aVal, aRadix); |
|
1999 } |
|
2000 |
|
2001 /** |
|
2002 Formats and appends text onto the end of this descriptor's data. |
|
2003 |
|
2004 The length of this descriptor is incremented to reflect the new content. |
|
2005 |
|
2006 The function takes a format string and a variable number of arguments. |
|
2007 The format string contains literal text, embedded with directives, |
|
2008 for converting the trailing list of arguments into text. |
|
2009 |
|
2010 The embedded directives are character sequences prefixed with the '%' character. |
|
2011 The literal text is simply copied into this descriptor unaltered while |
|
2012 the '%' directives are used to convert successive arguments from the |
|
2013 trailing list. See the description of the Format() function. |
|
2014 |
|
2015 Literal text is appended on a character by character basis, and the |
|
2016 underlying buffer is grown as necessary to accommodate it. |
|
2017 |
|
2018 Text converted from a trailing argument is appended as a complete |
|
2019 string, and the underlying buffer is grown as necessary to accommodate |
|
2020 it. |
|
2021 |
|
2022 This leaving variant of the standard, non-leaving descriptor method |
|
2023 differs in that this operation may cause the string descriptor's heap |
|
2024 buffer to be reallocated in order to accommodate the new data. As a |
|
2025 result, MaxLength() and Ptr() may return different values afterwards, |
|
2026 and any existing raw pointers to into the descriptor data may be |
|
2027 invalidated. |
|
2028 |
|
2029 @param aFmt The 16-bit non-modifiable descriptor containing the |
|
2030 format string. The TRefByValue class provides a |
|
2031 constructor which takes a TDesC16 type. |
|
2032 |
|
2033 @param ... A variable number of arguments to be converted to text |
|
2034 as dictated by the format string. |
|
2035 |
|
2036 @leave KErrNoMemory if the underlying buffer needs to be |
|
2037 grown and there are insufficient resources to do so |
|
2038 |
|
2039 @panic USER 12 if the format string has incorrect syntax. |
|
2040 |
|
2041 @see TDes16::Format() |
|
2042 @see TDes16Overflow::Overflow() |
|
2043 */ |
|
2044 EXPORT_C void LString16::AppendFormatL(TRefByValue<const TDesC16> aFmt,...) |
|
2045 { |
|
2046 VA_LIST list; |
|
2047 VA_START(list,aFmt); |
|
2048 AppendFormatListL(aFmt,list); |
|
2049 } |
|
2050 |
|
2051 class TRetryOverflow16 : public TDes16Overflow |
|
2052 { |
|
2053 public: |
|
2054 TRetryOverflow16() : iOverflow(EFalse) |
|
2055 { |
|
2056 } |
|
2057 |
|
2058 virtual void Overflow(TDes16& /*aDes*/) |
|
2059 { |
|
2060 iOverflow = ETrue; |
|
2061 } |
|
2062 |
|
2063 TBool iOverflow; |
|
2064 }; |
|
2065 |
|
2066 /** |
|
2067 Formats and appends text onto the end of this descriptor's data. |
|
2068 |
|
2069 The length of this descriptor is incremented to reflect the new content. |
|
2070 |
|
2071 The behaviour of this function is the same as |
|
2072 AppendFormatL(TRefByValue<const TDesC16> aFmt,TDes16Overflow *aOverflowHandler,...). |
|
2073 In practice, it is better and easier to use AppendFormat(), passing a variable number of |
|
2074 arguments as required by the format string. |
|
2075 |
|
2076 This leaving variant of the standard, non-leaving descriptor method |
|
2077 differs in that this operation may cause the string descriptor's heap |
|
2078 buffer to be reallocated in order to accommodate the new data. As a |
|
2079 result, MaxLength() and Ptr() may return different values afterwards, |
|
2080 and any existing raw pointers to into the descriptor data may be |
|
2081 invalidated. |
|
2082 |
|
2083 @param aFmt The descriptor containing the format string. |
|
2084 @param aList A pointer to an argument list. |
|
2085 |
|
2086 @leave KErrNoMemory if the underlying buffer needs to be |
|
2087 grown and there are insufficient resources to do so |
|
2088 |
|
2089 @see TDes16::AppendFormat |
|
2090 @see VA_LIST |
|
2091 */ |
|
2092 EXPORT_C void LString16::AppendFormatListL(const TDesC16& aFmt,VA_LIST aList) |
|
2093 { |
|
2094 ReserveFreeCapacityGrowExponentialL(aFmt.Length() + KDefaultExpandSize); // We use aFmt as a hint |
|
2095 for (;;) |
|
2096 { |
|
2097 TInt before = Length(); |
|
2098 TRetryOverflow16 overflow; |
|
2099 RBuf16::AppendFormatList(aFmt, aList, &overflow); |
|
2100 if (overflow.iOverflow) |
|
2101 { |
|
2102 SetLengthL(before); // Can't leave |
|
2103 ReserveCapacityGrowExponentialL(); |
|
2104 } |
|
2105 else |
|
2106 { |
|
2107 break; |
|
2108 } |
|
2109 } |
|
2110 } |
|
2111 |
|
2112 |
|
2113 /** |
|
2114 Unlinks and transfers ownership of the specified 16-bit resizable descriptor's |
|
2115 buffer to this object. The source descriptor is detached from the buffer. |
|
2116 |
|
2117 @param aString The source 16-bit resizable buffer. The ownership of this |
|
2118 object's buffer is to be transferred. |
|
2119 |
|
2120 @see RBuf16::Close() |
|
2121 */ |
|
2122 EXPORT_C void LString16::Assign(const LString16& aString) |
|
2123 { |
|
2124 // free any previously owned resource |
|
2125 Reset(); |
|
2126 |
|
2127 RBuf16::Assign(aString); |
|
2128 // unlink buffer from original descriptor |
|
2129 new (const_cast<LString16*>(&aString)) LString16(); |
|
2130 } |
|
2131 |
|
2132 |
|
2133 /** |
|
2134 Transfers ownership of the specified 16-bit resizable descriptor's |
|
2135 buffer to this object. The source descriptor is detached from the buffer. |
|
2136 |
|
2137 @param aRBuf The source 16-bit resizable buffer. The ownership of this |
|
2138 object's buffer is to be transferred. |
|
2139 |
|
2140 @see RBuf16::Assign() |
|
2141 */ |
|
2142 |
|
2143 EXPORT_C void LString16::Assign(const RBuf16& aRBuf) |
|
2144 { |
|
2145 // free any previously owned resource |
|
2146 Reset(); |
|
2147 |
|
2148 RBuf16::Assign(aRBuf); |
|
2149 |
|
2150 // reset the RBuf; |
|
2151 new (const_cast<RBuf16*>(&aRBuf)) RBuf16(); |
|
2152 } |
|
2153 |
|
2154 |
|
2155 /** |
|
2156 Transfers ownership of the specified 16-bit resizable descriptor's this object. |
|
2157 |
|
2158 @param aHBuf The heap descriptor to be transferred to this object. |
|
2159 The ownership of this object's buffer is to be transferred. |
|
2160 |
|
2161 @see RBuf16::Assign() |
|
2162 */ |
|
2163 EXPORT_C void LString16::Assign(HBufC16* aHBuf) |
|
2164 { |
|
2165 // free any previously owned resource |
|
2166 Reset(); |
|
2167 |
|
2168 RBuf16::Assign(aHBuf); |
|
2169 } |
|
2170 |
|
2171 |
|
2172 /** |
|
2173 Assigns ownership of the specified allocated memory to this object. |
|
2174 |
|
2175 @param aHeapCell The allocated memory to be assigned to this object. |
|
2176 This pointer can be NULL, which means that a zero length |
|
2177 16-bit resizable buffer descriptor is created. |
|
2178 |
|
2179 @param aMaxLength The maximum length of the descriptor. |
|
2180 |
|
2181 @panic USER 8 If the specified maximum length is greater then the size of the |
|
2182 allocated heap cell, or the specified maximum length is NOT |
|
2183 zero when the pointer to the heap cell is NULL. |
|
2184 |
|
2185 @see RBuf16::Close() |
|
2186 @see RBuf16::Assign() |
|
2187 */ |
|
2188 EXPORT_C void LString16::Assign(TUint16* aHeapCell, TInt aMaxLength) |
|
2189 { |
|
2190 // free any previously owned resource |
|
2191 Reset(); |
|
2192 |
|
2193 RBuf16::Assign(aHeapCell, aMaxLength); |
|
2194 } |
|
2195 |
|
2196 |
|
2197 /** |
|
2198 Transfers ownership of the specified 16-bit resizable descriptor's this object. |
|
2199 |
|
2200 @param aHeapCell The allocated memory to be assigned to this object. |
|
2201 |
|
2202 @param aLength The length of the descriptor. |
|
2203 |
|
2204 @param aMaxLength The maximum length of the descriptor. |
|
2205 |
|
2206 @panic USER 8 If the specified maximum length is greater then the size of the |
|
2207 allocated heap cell, or the specified length is greater then |
|
2208 the specified maximum length, or the specified maximum length |
|
2209 is NOT zero when the pointer to the heap cell is NULL. |
|
2210 |
|
2211 @see RBuf16::Close() |
|
2212 @see RBuf16::Assign() |
|
2213 */ |
|
2214 EXPORT_C void LString16::Assign(TUint16* aHeapCell,TInt aLength,TInt aMaxLength) |
|
2215 { |
|
2216 // free any previously owned resource |
|
2217 Reset(); |
|
2218 |
|
2219 RBuf16::Assign(aHeapCell, aLength, aMaxLength); |
|
2220 } |
|
2221 |
|
2222 /** |
|
2223 Creates a 16-bit resizable buffer descriptor that has been initialised with |
|
2224 data from the specified read stream; leaves on failure. |
|
2225 |
|
2226 Data is assigned to the new descriptor from the specified stream. |
|
2227 This variant assumes that the stream contains the length of the data followed |
|
2228 by the data itself. |
|
2229 |
|
2230 The function is implemented by calling the HBufC16::NewL(RReadStream&,TInt) |
|
2231 variant and then assigning the resulting heap descriptor using |
|
2232 the RBuf16::Assign(HBufC16*) variant. The comments that describe |
|
2233 the HBufC16::NewL() variant also apply to this RBuf16::CreateL() function. |
|
2234 |
|
2235 The function may leave with one of the system-wide error codes, specifically |
|
2236 KErrOverflow, if the length of the data as read from the stream is greater than |
|
2237 the upper limit as specified by the aMaxLength parameter. |
|
2238 |
|
2239 @param aStream The stream from which the data length and the data to be |
|
2240 assigned to the new descriptor, are taken. |
|
2241 @param aMaxLength The upper limit on the length of data that the descriptor is |
|
2242 to represent. The value of this parameter must be non-negative |
|
2243 otherwise the underlying function will panic. |
|
2244 */ |
|
2245 EXPORT_C void LString16::CreateL(RReadStream &aStream,TInt aMaxLength) |
|
2246 { |
|
2247 Reset(); |
|
2248 Assign(HBufC16::NewL(aStream,aMaxLength)); |
|
2249 } |
|
2250 |
|
2251 /** |
|
2252 Appends data onto the end of this descriptor's data. |
|
2253 |
|
2254 The length of this descriptor is incremented to reflect the new content. |
|
2255 |
|
2256 This leaving variant of the standard, non-leaving descriptor method |
|
2257 differs in that this operation may cause the string descriptor's heap |
|
2258 buffer to be reallocated in order to accommodate the new data. As a |
|
2259 result, MaxLength() and Ptr() may return different values afterwards, |
|
2260 and any existing raw pointers to into the descriptor data may be |
|
2261 invalidated. |
|
2262 |
|
2263 @param aZeroTerminatedString A pointer to a zero terminated string . |
|
2264 @leave KErrNoMemory if the underlying buffer needs to be |
|
2265 grown and there are insufficient resources to do so |
|
2266 |
|
2267 @see LString16::AppendL |
|
2268 */ |
|
2269 EXPORT_C LString16& LString16::operator+=(const TUint16* aZeroTerminatedString) |
|
2270 { |
|
2271 AppendL(aZeroTerminatedString,User::StringLength(aZeroTerminatedString)); |
|
2272 return *this; |
|
2273 } |
|
2274 /** |
|
2275 Appends data onto the end of this descriptor's data. |
|
2276 |
|
2277 The length of this descriptor is incremented to reflect the new content. |
|
2278 |
|
2279 This leaving variant of the standard, non-leaving descriptor method |
|
2280 differs in that this operation may cause the string descriptor's heap |
|
2281 buffer to be reallocated in order to accommodate the new data. As a |
|
2282 result, MaxLength() and Ptr() may return different values afterwards, |
|
2283 and any existing raw pointers to into the descriptor data may be |
|
2284 invalidated. |
|
2285 |
|
2286 @param aZeroTerminatedString A pointer to the data to be copied. |
|
2287 |
|
2288 @leave KErrNoMemory if the underlying buffer needs to be |
|
2289 grown and there are insufficient resources to do so |
|
2290 |
|
2291 @panic USER 17 if aLength is negative. |
|
2292 */ |
|
2293 EXPORT_C void LString16::AppendL(const TUint16* aZeroTerminatedString) |
|
2294 { |
|
2295 AppendL(aZeroTerminatedString,User::StringLength(aZeroTerminatedString)); |
|
2296 } |
|
2297 |
|
2298 /** |
|
2299 Constructor to create a 16-bit resizable string descriptor containing |
|
2300 a copy of the specified (source) zero-terminated wide character string data, or leave |
|
2301 on failure. |
|
2302 |
|
2303 The constructor allocates sufficient memory so that this string |
|
2304 descriptor's maximum length is the same as the length of the source |
|
2305 string. Both the current length and the maximum length of this string |
|
2306 descriptor are set to the length of the source string. |
|
2307 |
|
2308 The data contained in the source string is copied into this string |
|
2309 descriptor. The zero terminator is not copied. |
|
2310 |
|
2311 @param aWideCharStr A pointer to a zero-terminated wide character string |
|
2312 |
|
2313 @leave KErrNoMemory If there is insufficient memory. |
|
2314 |
|
2315 @see LString16::CopyL |
|
2316 */ |
|
2317 EXPORT_C LString16::LString16(const wchar_t* aWideCharStr) |
|
2318 : iReserved(0) |
|
2319 { |
|
2320 CopyL(reinterpret_cast<const TUint16*>(aWideCharStr)); |
|
2321 } |
|
2322 |
|
2323 /** |
|
2324 Copies data into this 16-bit string descriptor, replacing any existing |
|
2325 data, and expanding its heap buffer to accommodate if necessary. |
|
2326 |
|
2327 The length of this descriptor is set to reflect the new data. |
|
2328 |
|
2329 This operation may cause the target string descriptor's heap buffer to |
|
2330 be reallocated in order to accommodate the new data. As a result, |
|
2331 MaxLength() and Ptr() may return different values afterwards, and any |
|
2332 existing raw pointers to into the descriptor data may be invalidated. |
|
2333 |
|
2334 Note that the automatic resizing performed is a change to the |
|
2335 functionality of this operation compared to other descriptor |
|
2336 classes. This change is only active on objects directly declared |
|
2337 LString16; when LString16 instances are instead manipulated via |
|
2338 references to TDes16 or TDesC16, the standard (non-resizing, panicing) |
|
2339 variant is invoked. |
|
2340 |
|
2341 @param aWideCharStr A pointer to a wide character zero-terminated string |
|
2342 |
|
2343 @return A reference to this 16-bit string descriptor. |
|
2344 |
|
2345 @leave KErrNoMemory If the heap buffer of the string descriptor being |
|
2346 assigned to needs to be expanded, but there is |
|
2347 insufficient memory to do so |
|
2348 |
|
2349 @see LString16::CopyL |
|
2350 */ |
|
2351 EXPORT_C LString16& LString16::operator=(const wchar_t* aWideCharStr) |
|
2352 { |
|
2353 CopyL(reinterpret_cast<const TUint16*>(aWideCharStr)); |
|
2354 return *this; |
|
2355 } |
|
2356 |
|
2357 /** |
|
2358 Appends data onto the end of this descriptor's data. |
|
2359 |
|
2360 The length of this descriptor is incremented to reflect the new content. |
|
2361 |
|
2362 This leaving variant of the standard, non-leaving descriptor method |
|
2363 differs in that this operation may cause the string descriptor's heap |
|
2364 buffer to be reallocated in order to accommodate the new data. As a |
|
2365 result, MaxLength() and Ptr() may return different values afterwards, |
|
2366 and any existing raw pointers to into the descriptor data may be |
|
2367 invalidated. |
|
2368 |
|
2369 @param aWideCharStr A pointer to a wide character zero terminated string . |
|
2370 @leave KErrNoMemory if the underlying buffer needs to be |
|
2371 grown and there are insufficient resources to do so |
|
2372 |
|
2373 @see LString16::AppendL |
|
2374 */ |
|
2375 EXPORT_C LString16& LString16::operator+=(const wchar_t* aWideCharStr) |
|
2376 { |
|
2377 AppendL(reinterpret_cast<const TUint16*>(aWideCharStr),User::StringLength(reinterpret_cast<const TUint16*>(aWideCharStr))); |
|
2378 return *this; |
|
2379 } |
|
2380 |
|
2381 /** |
|
2382 Copies data into this 16-bit string descriptor, replacing any existing |
|
2383 data, and expanding its heap buffer to accommodate if necessary. |
|
2384 |
|
2385 This leaving variant of the standard, non-leaving descriptor method |
|
2386 differs in that this operation may cause the string descriptor's heap |
|
2387 buffer to be reallocated in order to accommodate the new data. As a |
|
2388 result, MaxLength() and Ptr() may return different values afterwards, |
|
2389 and any existing raw pointers to into the descriptor data may be |
|
2390 invalidated. |
|
2391 |
|
2392 @param aWideCharStr A pointer to a wide character zero terminated string to be copied. |
|
2393 |
|
2394 |
|
2395 @leave KErrNoMemory If the heap buffer of the string descriptor being |
|
2396 assigned to needs to be expanded, but there is |
|
2397 insufficient memory to do so |
|
2398 |
|
2399 @panic USER 11 if aLength is negative. |
|
2400 |
|
2401 @see TDes16::Copy |
|
2402 */ |
|
2403 EXPORT_C void LString16::CopyL(const wchar_t* aWideCharStr) |
|
2404 { |
|
2405 CopyL(reinterpret_cast<const TUint16*>(aWideCharStr)); |
|
2406 } |
|
2407 |
|
2408 /** |
|
2409 Appends data onto the end of this descriptor's data and justifies it. |
|
2410 |
|
2411 The source of the appended data is a memory location. |
|
2412 |
|
2413 The target area is considered to be an area of specified width, immediately |
|
2414 following this descriptor's existing data. Source data is copied into, and |
|
2415 aligned within, this target area according to the specified alignment instruction. |
|
2416 |
|
2417 If the length of the target area is larger than the length of the source, |
|
2418 then spare space within the target area is padded with the fill character. |
|
2419 |
|
2420 This leaving variant of the standard, non-leaving descriptor method |
|
2421 differs in that this operation may cause the string descriptor's heap |
|
2422 buffer to be reallocated in order to accommodate the new data. As a |
|
2423 result, MaxLength() and Ptr() may return different values afterwards, |
|
2424 and any existing raw pointers to into the descriptor data may be |
|
2425 invalidated. |
|
2426 |
|
2427 @param aWideCharStr A pointer to a source memory location. |
|
2428 |
|
2429 @param aLength The length of data to be copied. If this is greater than the |
|
2430 width of the target area, then the length of data copied is |
|
2431 limited to the width. |
|
2432 |
|
2433 @param aWidth The width of the target area. If this has the specific negative |
|
2434 value KDefaultJustifyWidth, then the width is |
|
2435 re-set to the length of the data source. |
|
2436 |
|
2437 @param aAlignment The alignment of the data within the target area. |
|
2438 |
|
2439 @param aFill The fill character used to pad the target area. |
|
2440 |
|
2441 @leave KErrNoMemory if the underlying buffer needs to be |
|
2442 grown and there are insufficient resources to do so |
|
2443 |
|
2444 @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. |
|
2445 |
|
2446 @panic USER 17 if aLength is negative. |
|
2447 */ |
|
2448 EXPORT_C void LString16::AppendJustifyL(const wchar_t* aWideCharStr,TInt aWidth,TAlign anAlignment,TChar aFill) |
|
2449 { |
|
2450 AppendJustifyL(reinterpret_cast<const TUint16*>( aWideCharStr),aWidth,anAlignment,aFill); |
|
2451 } |
|
2452 |
|
2453 /** |
|
2454 Appends data onto the end of this descriptor's data. |
|
2455 |
|
2456 The length of this descriptor is incremented to reflect the new content. |
|
2457 |
|
2458 This leaving variant of the standard, non-leaving descriptor method |
|
2459 differs in that this operation may cause the string descriptor's heap |
|
2460 buffer to be reallocated in order to accommodate the new data. As a |
|
2461 result, MaxLength() and Ptr() may return different values afterwards, |
|
2462 and any existing raw pointers to into the descriptor data may be |
|
2463 invalidated. |
|
2464 |
|
2465 @param aWideCharStr A pointer to the data to be copied. |
|
2466 @param aLength The length of data to be copied. |
|
2467 |
|
2468 @leave KErrNoMemory if the underlying buffer needs to be |
|
2469 grown and there are insufficient resources to do so |
|
2470 |
|
2471 @panic USER 17 if aLength is negative. |
|
2472 */ |
|
2473 EXPORT_C void LString16::AppendL(const wchar_t* aWideCharStr,TInt aLength) |
|
2474 { |
|
2475 AppendL(reinterpret_cast<const TUint16*>(aWideCharStr),aLength); |
|
2476 } |
|
2477 /** |
|
2478 Appends data onto the end of this descriptor's data. |
|
2479 |
|
2480 The length of this descriptor is incremented to reflect the new content. |
|
2481 |
|
2482 This leaving variant of the standard, non-leaving descriptor method |
|
2483 differs in that this operation may cause the string descriptor's heap |
|
2484 buffer to be reallocated in order to accommodate the new data. As a |
|
2485 result, MaxLength() and Ptr() may return different values afterwards, |
|
2486 and any existing raw pointers to into the descriptor data may be |
|
2487 invalidated. |
|
2488 |
|
2489 @param aWideCharStr A pointer to the data to be copied. |
|
2490 |
|
2491 @leave KErrNoMemory if the underlying buffer needs to be |
|
2492 grown and there are insufficient resources to do so |
|
2493 |
|
2494 @panic USER 17 if aLength is negative. |
|
2495 */ |
|
2496 EXPORT_C void LString16::AppendL(const wchar_t* aWideCharStr) |
|
2497 { |
|
2498 AppendL(reinterpret_cast<const TUint16*>(aWideCharStr)); |
|
2499 } |
|
2500 /** |
|
2501 Determines whether this Descriptor's data is equal to the specified |
|
2502 string's data. |
|
2503 |
|
2504 The comparison is implemented internally using the TDesC::Compare() function. |
|
2505 |
|
2506 @param aWideCharStr The wide character string whose data is to be compared |
|
2507 with this Descriptor's data. |
|
2508 |
|
2509 @return True if equal, false otherwise. |
|
2510 |
|
2511 @see TDesC::Compare |
|
2512 */ |
|
2513 EXPORT_C TBool LString16::operator==( const wchar_t* aWideCharStr) const |
|
2514 { |
|
2515 return LString16::operator==(reinterpret_cast<const TUint16*>(aWideCharStr)); |
|
2516 } |
|
2517 |
|
2518 /** |
|
2519 Determines whether this Descriptor's data is equal to the specified |
|
2520 string's data. |
|
2521 |
|
2522 The comparison is implemented internally using the TDesC::Compare() function. |
|
2523 |
|
2524 @param aZeroTerminatedString The wide Zero TerminatedString string whose data |
|
2525 is to be compared with this Descriptor's data. |
|
2526 |
|
2527 @return True if equal, false otherwise. |
|
2528 |
|
2529 @see TDesC::Compare |
|
2530 */ |
|
2531 EXPORT_C TBool LString16::operator==( const TUint16* aZeroTerminatedString) const |
|
2532 { |
|
2533 return RBuf16::operator==(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
2534 } |
|
2535 |
|
2536 /** |
|
2537 Determines whether this descriptor's data is less than the specified |
|
2538 strings's data. |
|
2539 |
|
2540 The comparison is implemented internally using the TDesC::Compare() function. |
|
2541 |
|
2542 @param aWideCharStr The wide character string whose data is to be compared |
|
2543 with this Descriptor's data. |
|
2544 |
|
2545 @return True if this descriptor's data is less than that of the specified string's data |
|
2546 |
|
2547 @see TDesC::Compare |
|
2548 */ |
|
2549 EXPORT_C TBool LString16::operator<( const wchar_t* aWideCharStr) const |
|
2550 { |
|
2551 return LString16::operator<(reinterpret_cast<const TUint16*>(aWideCharStr)); |
|
2552 } |
|
2553 |
|
2554 /** |
|
2555 Determines whether this descriptor's data is less than the specified |
|
2556 strings's data. |
|
2557 |
|
2558 The comparison is implemented internally using the TDesC::Compare() function. |
|
2559 |
|
2560 @param aZeroTerminatedString The wide Zero TerminatedString string whose data |
|
2561 is to be compared with this Descriptor's data. |
|
2562 |
|
2563 @return True if this descriptor's data is less than that of the specified string's data |
|
2564 |
|
2565 @see TDesC::Compare |
|
2566 */ |
|
2567 EXPORT_C TBool LString16::operator<(const TUint16* aZeroTerminatedString) const |
|
2568 { |
|
2569 return RBuf16::operator<(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
2570 } |
|
2571 |
|
2572 /** |
|
2573 Determines whether this descriptor's data is less than the specified |
|
2574 strings's data. |
|
2575 |
|
2576 The comparison is implemented internally using the TDesC::Compare() function. |
|
2577 |
|
2578 @param aWideCharStr The wide character string whose data is to be compared |
|
2579 with this Descriptor's data. |
|
2580 |
|
2581 @return True if this descriptor's data is less than that of the specified string's data |
|
2582 |
|
2583 @see TDesC::Compare |
|
2584 */ |
|
2585 EXPORT_C TBool LString16::operator<=( const wchar_t* aWideCharStr) const |
|
2586 { |
|
2587 return LString16::operator<=(reinterpret_cast<const TUint16*>(aWideCharStr)); |
|
2588 } |
|
2589 |
|
2590 /** |
|
2591 Determines whether this descriptor's data is less than/equal to the specified |
|
2592 strings's data. |
|
2593 |
|
2594 The comparison is implemented internally using the TDesC::Compare() function. |
|
2595 |
|
2596 @param aZeroTerminatedString The wide Zero TerminatedString string whose data |
|
2597 is to be compared with this Descriptor's data. |
|
2598 |
|
2599 @return True if this descriptor's data is less than/equal to that of the specified string's data |
|
2600 |
|
2601 @see TDesC::Compare |
|
2602 */ |
|
2603 EXPORT_C TBool LString16::operator<=(const TUint16* aZeroTerminatedString) const |
|
2604 { |
|
2605 return RBuf16::operator<=(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
2606 } |
|
2607 |
|
2608 /** |
|
2609 Determines whether this descriptor's data is greater than the specified |
|
2610 strings's data. |
|
2611 |
|
2612 The comparison is implemented internally using the TDesC::Compare() function. |
|
2613 |
|
2614 @param aWideCharStr The wide character string whose data is to be compared |
|
2615 with this Descriptor's data. |
|
2616 |
|
2617 @return True if this descriptor's data is greater than that of the specified string's data |
|
2618 |
|
2619 @see TDesC::Compare |
|
2620 */ |
|
2621 EXPORT_C TBool LString16::operator>( const wchar_t* aWideCharStr) const |
|
2622 { |
|
2623 return LString16::operator>(reinterpret_cast<const TUint16*>(aWideCharStr)); |
|
2624 } |
|
2625 |
|
2626 /** |
|
2627 Determines whether this descriptor's data is greater than the specified |
|
2628 strings's data. |
|
2629 |
|
2630 The comparison is implemented internally using the TDesC::Compare() function. |
|
2631 |
|
2632 @param aZeroTerminatedString The wide Zero TerminatedString string whose data |
|
2633 is to be compared with this Descriptor's data. |
|
2634 |
|
2635 @return True if this descriptor's data is greater than that of the specified string's data |
|
2636 |
|
2637 @see TDesC::Compare |
|
2638 */ |
|
2639 EXPORT_C TBool LString16::operator>(const TUint16* aZeroTerminatedString) const |
|
2640 { |
|
2641 return RBuf16::operator>(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
2642 } |
|
2643 |
|
2644 /** |
|
2645 Determines whether this descriptor's data is greater than/equal to the specified |
|
2646 strings's data. |
|
2647 |
|
2648 The comparison is implemented internally using the TDesC::Compare() function. |
|
2649 |
|
2650 @param aWideCharStr The wide character string whose data is to be compared |
|
2651 with this Descriptor's data. |
|
2652 |
|
2653 @return True if this descriptor's data is greater than/equal to that of the specified string's data |
|
2654 |
|
2655 @see TDesC::Compare |
|
2656 */ |
|
2657 EXPORT_C TBool LString16::operator>=( const wchar_t* aWideCharStr) const |
|
2658 { |
|
2659 return LString16::operator>=(reinterpret_cast<const TUint16*>(aWideCharStr)); |
|
2660 } |
|
2661 |
|
2662 /** |
|
2663 Determines whether this descriptor's data is greater than the specified |
|
2664 strings's data. |
|
2665 |
|
2666 The comparison is implemented internally using the TDesC::Compare() function. |
|
2667 |
|
2668 @param aZeroTerminatedString The wide Zero TerminatedString string whose data |
|
2669 is to be compared with this Descriptor's data. |
|
2670 |
|
2671 @return True if this descriptor's data is greater than that of the specified string's data |
|
2672 |
|
2673 @see TDesC::Compare |
|
2674 */ |
|
2675 EXPORT_C TBool LString16::operator>=(const TUint16* aZeroTerminatedString) const |
|
2676 { |
|
2677 return RBuf16::operator>=(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
2678 } |
|
2679 |
|
2680 /** |
|
2681 Determines whether this descriptor's data is not equal to the specified |
|
2682 strings's data. |
|
2683 |
|
2684 The comparison is implemented internally using the TDesC::Compare() function. |
|
2685 |
|
2686 @param aWideCharStr The wide character string whose data is to be compared |
|
2687 with this Descriptor's data. |
|
2688 |
|
2689 @return True if this descriptor's data is not equal to the specified string's data |
|
2690 |
|
2691 @see TDesC::Compare |
|
2692 */ |
|
2693 EXPORT_C TBool LString16::operator!=( const wchar_t* aWideCharStr) const |
|
2694 { |
|
2695 return LString16::operator!=(reinterpret_cast<const TUint16*>(aWideCharStr)); |
|
2696 } |
|
2697 |
|
2698 /** |
|
2699 Determines whether this descriptor's data is not equal to the specified |
|
2700 strings's data. |
|
2701 |
|
2702 The comparison is implemented internally using the TDesC::Compare() function. |
|
2703 |
|
2704 @param aZeroTerminatedString The wide Zero TerminatedString string whose data |
|
2705 is to be compared with this Descriptor's data. |
|
2706 |
|
2707 @return True if this descriptor's data is not equal to the specified string's data |
|
2708 |
|
2709 @see TDesC::Compare |
|
2710 */ |
|
2711 EXPORT_C TBool LString16::operator!=(const TUint16* aZeroTerminatedString) const |
|
2712 { |
|
2713 return RBuf16::operator!=(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
2714 } |
|
2715 |
|
2716 /** |
|
2717 Searches this descriptor's data for a match with the match pattern supplied |
|
2718 in the specified string. |
|
2719 |
|
2720 The match pattern can contain the wildcard characters "*" and "?", where "*" |
|
2721 matches zero or more consecutive occurrences of any character and "?" matches |
|
2722 a single occurrence of any character. |
|
2723 |
|
2724 Note that there is no 'escape character', which means that it is not possible |
|
2725 to match either the "*" character itself or the "?" character itself using |
|
2726 this function. |
|
2727 |
|
2728 @param aWideCharStr The wide character string whose data is to be matched |
|
2729 with this Descriptor's data. |
|
2730 |
|
2731 @return If a match is found, the offset within this descriptor's data where |
|
2732 the match first occurs. KErrNotFound, if there is no match. |
|
2733 */ |
|
2734 EXPORT_C TInt LString16::Match(const wchar_t* aWideCharStr) const |
|
2735 { |
|
2736 return LString16::Match(reinterpret_cast<const TUint16*>(aWideCharStr)); |
|
2737 } |
|
2738 |
|
2739 /** |
|
2740 Searches this descriptor's data for a match with the match pattern supplied |
|
2741 in the specified string. |
|
2742 |
|
2743 The match pattern can contain the wildcard characters "*" and "?", where "*" |
|
2744 matches zero or more consecutive occurrences of any character and "?" matches |
|
2745 a single occurrence of any character. |
|
2746 |
|
2747 Note that there is no 'escape character', which means that it is not possible |
|
2748 to match either the "*" character itself or the "?" character itself using |
|
2749 this function. |
|
2750 |
|
2751 @param aZeroTerminatedString The wide Zero TerminatedString string whose data |
|
2752 is to be matched with this Descriptor's data. |
|
2753 |
|
2754 @return If a match is found, the offset within this descriptor's data where |
|
2755 the match first occurs. KErrNotFound, if there is no match. |
|
2756 */ |
|
2757 EXPORT_C TInt LString16::Match(const TUint16* aZeroTerminatedString) const |
|
2758 { |
|
2759 return RBuf16::Match(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
2760 } |
|
2761 /** |
|
2762 Searches this descriptor's folded data for a match with the folded match |
|
2763 pattern supplied in the specified string. |
|
2764 |
|
2765 The match pattern can contain the wildcard characters "*" and "?", where "*" |
|
2766 matches zero or more consecutive occurrences of any character and "?" matches |
|
2767 a single occurrence of any character. |
|
2768 |
|
2769 Note that folding is locale-independent behaviour. It is also important to |
|
2770 note that there can be no guarantee that folding is in any way culturally |
|
2771 appropriate, and should not be used for matching strings in natural language; |
|
2772 use MatchC() for this. |
|
2773 |
|
2774 Note that there is no 'escape character', which means that it is not possible |
|
2775 to match either the "*" character itself or the "?" character itself using |
|
2776 this function. |
|
2777 |
|
2778 @param aWideCharStr The wide character string whose data is to be matched |
|
2779 with this Descriptor's data. |
|
2780 |
|
2781 @return If a match is found, the offset within this descriptor's data where |
|
2782 the match first occurs. KErrNotFound, if there is no match. |
|
2783 |
|
2784 @see TDesC::MatchC() |
|
2785 */ |
|
2786 EXPORT_C TInt LString16::MatchF(const wchar_t* aWideCharStr) const |
|
2787 { |
|
2788 return LString16::MatchF(reinterpret_cast<const TUint16*>(aWideCharStr)); |
|
2789 } |
|
2790 /** |
|
2791 Searches this descriptor's folded data for a match with the folded match |
|
2792 pattern supplied in the specified string. |
|
2793 |
|
2794 The match pattern can contain the wildcard characters "*" and "?", where "*" |
|
2795 matches zero or more consecutive occurrences of any character and "?" matches |
|
2796 a single occurrence of any character. |
|
2797 |
|
2798 Note that folding is locale-independent behaviour. It is also important to |
|
2799 note that there can be no guarantee that folding is in any way culturally |
|
2800 appropriate, and should not be used for matching strings in natural language; |
|
2801 use MatchC() for this. |
|
2802 |
|
2803 Note that there is no 'escape character', which means that it is not possible |
|
2804 to match either the "*" character itself or the "?" character itself using |
|
2805 this function. |
|
2806 |
|
2807 @param aZeroTerminatedString The wide Zero TerminatedString string whose data |
|
2808 is to be matched with this Descriptor's data. |
|
2809 |
|
2810 @return If a match is found, the offset within this descriptor's data where |
|
2811 the match first occurs. KErrNotFound, if there is no match. |
|
2812 |
|
2813 @see TDesC::MatchC() |
|
2814 */ |
|
2815 EXPORT_C TInt LString16::MatchF(const TUint16* aZeroTerminatedString) const |
|
2816 { |
|
2817 return RBuf16::MatchF(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
2818 } |
|
2819 /** |
|
2820 Compares this descriptor's data with the specified string's data. |
|
2821 |
|
2822 The comparison proceeds on a byte for byte basis. The result of the comparison |
|
2823 is based on the difference of the first bytes to disagree. |
|
2824 |
|
2825 @param aWideCharStr The wide character string whose data is to be compared |
|
2826 with this Descriptor's data. |
|
2827 |
|
2828 @return Positive, if this descriptor is greater than the specified string. |
|
2829 Negative, if this descriptor is less than the specified string. |
|
2830 Zero, if both the descriptor and the string have the same length |
|
2831 and the their contents are the same. |
|
2832 */ |
|
2833 EXPORT_C TInt LString16::Compare(const wchar_t* aWideCharStr) const |
|
2834 { |
|
2835 return LString16::Compare(reinterpret_cast<const TUint16*>(aWideCharStr)); |
|
2836 } |
|
2837 |
|
2838 /** |
|
2839 Compares this descriptor's data with the specified string's data. |
|
2840 |
|
2841 The comparison proceeds on a byte for byte basis. The result of the comparison |
|
2842 is based on the difference of the first bytes to disagree. |
|
2843 |
|
2844 @param aZeroTerminatedString The wide Zero TerminatedString string whose data |
|
2845 is to be compared with this Descriptor's data. |
|
2846 |
|
2847 @return Positive, if this descriptor is greater than the specified string. |
|
2848 Negative, if this descriptor is less than the specified string. |
|
2849 Zero, if both the descriptor and the string have the same length |
|
2850 and the their contents are the same. |
|
2851 */ |
|
2852 EXPORT_C TInt LString16::Compare(const TUint16* aZeroTerminatedString) const |
|
2853 { |
|
2854 return RBuf16::Compare(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
2855 } |
|
2856 /** |
|
2857 Compares this descriptor's folded data with the specified string's folded |
|
2858 data. |
|
2859 |
|
2860 Note that folding is locale-independent behaviour. It is also important to |
|
2861 note that there can be no guarantee that folding is in any way culturally |
|
2862 appropriate, and should not be used for comparing strings in natural language; |
|
2863 |
|
2864 @param aWideCharStr The wide character string whose data is to be compared |
|
2865 with this Descriptor's data. |
|
2866 |
|
2867 @return Positive, if this descriptor is greater than the specified string. |
|
2868 Negative, if this descriptor is less than the specified string. |
|
2869 Zero, if the descriptor and the specified string have the same length |
|
2870 and the their contents are the same. |
|
2871 |
|
2872 @see TDesC::Compare() |
|
2873 */ |
|
2874 EXPORT_C TInt LString16::CompareF(const wchar_t* aWideCharStr) const |
|
2875 { |
|
2876 return LString16::CompareF(reinterpret_cast<const TUint16*>(aWideCharStr)); |
|
2877 } |
|
2878 |
|
2879 /** |
|
2880 Compares this descriptor's folded data with the specified string's folded |
|
2881 data. |
|
2882 |
|
2883 Note that folding is locale-independent behaviour. It is also important to |
|
2884 note that there can be no guarantee that folding is in any way culturally |
|
2885 appropriate, and should not be used for comparing strings in natural language; |
|
2886 |
|
2887 @param aZeroTerminatedString The wide Zero Terminated String whose data |
|
2888 is to be compared with this string's data. |
|
2889 |
|
2890 @return Positive, if this descriptor is greater than the specified string. |
|
2891 Negative, if this descriptor is less than the specified string. |
|
2892 Zero, if the descriptor and the specified string have the same length |
|
2893 and the their contents are the same. |
|
2894 |
|
2895 @see TDesC::Compare() |
|
2896 */ |
|
2897 EXPORT_C TInt LString16::CompareF(const TUint16* aZeroTerminatedString) const |
|
2898 { |
|
2899 return RBuf16::CompareF(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
2900 } |
|
2901 |
|
2902 /** |
|
2903 Searches for the first occurrence of the specified data sequence within this |
|
2904 descriptor. |
|
2905 |
|
2906 Searching always starts at the beginning of this descriptor's data. |
|
2907 |
|
2908 @param aWideCharStr The wide character string whose data is to be searched for, |
|
2909 within this Descriptor's data. |
|
2910 |
|
2911 @return The offset of the data sequence from the beginning of this descriptor's |
|
2912 data. KErrNotFound, if the data sequence cannot be found. |
|
2913 */ |
|
2914 EXPORT_C TInt LString16::Find(const wchar_t* aWideCharStr) const |
|
2915 { |
|
2916 return LString16::Find(reinterpret_cast<const TUint16*>(aWideCharStr)); |
|
2917 } |
|
2918 |
|
2919 /** |
|
2920 Searches for the first occurrence of the specified data sequence within this |
|
2921 descriptor. |
|
2922 |
|
2923 Searching always starts at the beginning of this descriptor's data. |
|
2924 |
|
2925 @param aWideCharStr The wide character string whose data is to be searched for, |
|
2926 within this Descriptor's data. |
|
2927 |
|
2928 @return The offset of the data sequence from the beginning of this descriptor's |
|
2929 data. KErrNotFound, if the data sequence cannot be found. |
|
2930 */ |
|
2931 EXPORT_C TInt LString16::Find(const TUint16* aZeroTerminatedString) const |
|
2932 { |
|
2933 return RBuf16::Find(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
2934 } |
|
2935 |
|
2936 /** |
|
2937 Searches for the first occurrence of the specified data sequence within this |
|
2938 descriptor. |
|
2939 |
|
2940 Searching always starts at the beginning of this descriptor's data. |
|
2941 |
|
2942 @param aWideCharStr The wide character string whose data is to be searched for, |
|
2943 within this Descriptor's data. |
|
2944 @param aLenS The length of the data sequence to be searched for. This value |
|
2945 must not be negative, otherwise the function raises a panic. |
|
2946 |
|
2947 @return The offset of the data sequence from the beginning of this descriptor's |
|
2948 data. KErrNotFound, if the data sequence cannot be found. |
|
2949 |
|
2950 @panic USER 29 if aLenS is negative. |
|
2951 */ |
|
2952 EXPORT_C TInt LString16::Find(const wchar_t* aWideCharStr,TInt aLenS) const |
|
2953 { |
|
2954 return LString16::Find(reinterpret_cast<const TUint16*>(aWideCharStr), aLenS); |
|
2955 } |
|
2956 |
|
2957 /** |
|
2958 Searches for the first occurrence of the specified folded data sequence within |
|
2959 this descriptor's folded data. |
|
2960 |
|
2961 Searching always starts at the beginning of this descriptor's data. |
|
2962 |
|
2963 Note that folding is locale-independent behaviour. It is also important to |
|
2964 note that there can be no guarantee that folding is in any way culturally |
|
2965 appropriate, and should not be used for finding strings in natural language; |
|
2966 |
|
2967 @param aWideCharStr The wide character string whose data is to be searched for, |
|
2968 within this Descriptor's data. |
|
2969 |
|
2970 @return The offset of the data sequence from the beginning of this descriptor's |
|
2971 data. KErrNotFound, if the data sequence cannot be found. Zero, if the |
|
2972 length of the search data sequence is zero. |
|
2973 |
|
2974 */ |
|
2975 EXPORT_C TInt LString16::FindF(const wchar_t* aWideCharStr) const |
|
2976 { |
|
2977 return LString16::FindF(reinterpret_cast<const TUint16*>(aWideCharStr)); |
|
2978 } |
|
2979 |
|
2980 /** |
|
2981 Searches for the first occurrence of the specified folded data sequence within |
|
2982 this descriptor's folded data. |
|
2983 |
|
2984 Searching always starts at the beginning of this descriptor's data. |
|
2985 |
|
2986 Note that folding is locale-independent behaviour. It is also important to |
|
2987 note that there can be no guarantee that folding is in any way culturally |
|
2988 appropriate, and should not be used for finding strings in natural language; |
|
2989 |
|
2990 @param aWideCharStr The wide character string whose data is to be searched for, |
|
2991 within this Descriptor's data. |
|
2992 |
|
2993 @return The offset of the data sequence from the beginning of this descriptor's |
|
2994 data. KErrNotFound, if the data sequence cannot be found. Zero, if the |
|
2995 length of the search data sequence is zero. |
|
2996 |
|
2997 */ |
|
2998 EXPORT_C TInt LString16::FindF(const TUint16* aZeroTerminatedString) const |
|
2999 { |
|
3000 return RBuf16::FindF(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
3001 } |
|
3002 /** |
|
3003 Searches for the first occurrence of the specified folded data sequence within |
|
3004 this descriptor's folded data. |
|
3005 |
|
3006 Searching always starts at the beginning of this descriptor's data. |
|
3007 |
|
3008 Note that folding is locale-independent behaviour. It is also important to |
|
3009 note that there can be no guarantee that folding is in any way culturally |
|
3010 appropriate, and should not be used for finding strings in natural language; |
|
3011 |
|
3012 @param aWideCharStr The wide character string whose data is to be searched for, |
|
3013 within this Descriptor's data. |
|
3014 @param aLenS The length of the data sequence to be searched for. This value |
|
3015 must not be negative, otherwise the function raises a panic. |
|
3016 |
|
3017 @return The offset of the data sequence from the beginning of this descriptor's |
|
3018 data. KErrNotFound, if the data sequence cannot be found. Zero, if the |
|
3019 length of the search data sequence is zero. |
|
3020 |
|
3021 @panic USER 29 if aLenS is negative |
|
3022 |
|
3023 */ |
|
3024 EXPORT_C TInt LString16::FindF(const wchar_t* aWideCharStr, TInt aLen) const |
|
3025 { |
|
3026 return RBuf16::FindF(reinterpret_cast<const TUint16*>(aWideCharStr),aLen); |
|
3027 } |
|
3028 |
|
3029 /** |
|
3030 Copies and folds data from the specified string into this descriptor replacing |
|
3031 any existing data. |
|
3032 |
|
3033 The length of this descriptor is set to reflect the new |
|
3034 data. |
|
3035 |
|
3036 Note that folding is locale-independent behaviour. It is also important to |
|
3037 note that there can be no guarantee that folding is in any way culturally |
|
3038 appropriate, and should not be used when dealing with strings in natural |
|
3039 language. |
|
3040 |
|
3041 This leaving variant of the standard, non-leaving descriptor method |
|
3042 differs in that this operation may cause the string descriptor's heap |
|
3043 buffer to be reallocated in order to accommodate the new data. As a |
|
3044 result, MaxLength() and Ptr() may return different values afterwards, |
|
3045 and any existing raw pointers to into the descriptor data may be |
|
3046 invalidated. |
|
3047 |
|
3048 @param aWideCharStr A wide character string |
|
3049 |
|
3050 @leave KErrNoMemory if the underlying buffer needs to be |
|
3051 grown and there are insufficient resources to do so |
|
3052 */ |
|
3053 EXPORT_C void LString16:: CopyFL(const wchar_t* aWideCharStr ) |
|
3054 { |
|
3055 LString16::CopyFL(reinterpret_cast<const TUint16*>(aWideCharStr)); |
|
3056 } |
|
3057 |
|
3058 /** |
|
3059 Copies and folds data from the specified string into this descriptor replacing |
|
3060 any existing data. |
|
3061 |
|
3062 The length of this descriptor is set to reflect the new |
|
3063 data. |
|
3064 |
|
3065 Note that folding is locale-independent behaviour. It is also important to |
|
3066 note that there can be no guarantee that folding is in any way culturally |
|
3067 appropriate, and should not be used when dealing with strings in natural |
|
3068 language. |
|
3069 |
|
3070 This leaving variant of the standard, non-leaving descriptor method |
|
3071 differs in that this operation may cause the string descriptor's heap |
|
3072 buffer to be reallocated in order to accommodate the new data. As a |
|
3073 result, MaxLength() and Ptr() may return different values afterwards, |
|
3074 and any existing raw pointers to into the descriptor data may be |
|
3075 invalidated. |
|
3076 |
|
3077 @param aZeroTerminatedString A wide zero terminated string |
|
3078 |
|
3079 @leave KErrNoMemory if the underlying buffer needs to be |
|
3080 grown and there are insufficient resources to do so |
|
3081 */ |
|
3082 EXPORT_C void LString16:: CopyFL(const TUint16* aZeroTerminatedString ) |
|
3083 { |
|
3084 LString16::CopyFL(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
3085 } |
|
3086 |
|
3087 /** |
|
3088 Copies text from the specified string and converts it to lower case before |
|
3089 putting it into this descriptor, replacing any existing data. |
|
3090 |
|
3091 The length of this descriptor is set to reflect the new data. |
|
3092 |
|
3093 Conversion to lower case is implemented as appropriate to the current locale. |
|
3094 |
|
3095 This leaving variant of the standard, non-leaving descriptor method |
|
3096 differs in that this operation may cause the string descriptor's heap |
|
3097 buffer to be reallocated in order to accommodate the new data. As a |
|
3098 result, MaxLength() and Ptr() may return different values afterwards, |
|
3099 and any existing raw pointers to into the descriptor data may be |
|
3100 invalidated. |
|
3101 |
|
3102 @param aWideCharStr A wide character string. |
|
3103 |
|
3104 @leave KErrNoMemory if the underlying buffer needs to be |
|
3105 grown and there are insufficient resources to do so |
|
3106 */ |
|
3107 EXPORT_C void LString16:: CopyLCL(const wchar_t* aWideCharStr) |
|
3108 { |
|
3109 LString16::CopyLCL(reinterpret_cast<const TUint16*>(aWideCharStr)); |
|
3110 } |
|
3111 |
|
3112 /** |
|
3113 Copies text from the specified string and converts it to lower case before |
|
3114 putting it into this descriptor, replacing any existing data. |
|
3115 |
|
3116 The length of this descriptor is set to reflect the new data. |
|
3117 |
|
3118 Conversion to lower case is implemented as appropriate to the current locale. |
|
3119 |
|
3120 This leaving variant of the standard, non-leaving descriptor method |
|
3121 differs in that this operation may cause the string descriptor's heap |
|
3122 buffer to be reallocated in order to accommodate the new data. As a |
|
3123 result, MaxLength() and Ptr() may return different values afterwards, |
|
3124 and any existing raw pointers to into the descriptor data may be |
|
3125 invalidated. |
|
3126 |
|
3127 @param aZeroTerminatedString A wide zero terminated string. |
|
3128 |
|
3129 @leave KErrNoMemory if the underlying buffer needs to be |
|
3130 grown and there are insufficient resources to do so |
|
3131 */ |
|
3132 EXPORT_C void LString16:: CopyLCL(const TUint16* aZeroTerminatedString) |
|
3133 { |
|
3134 LString16::CopyLCL(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
3135 } |
|
3136 |
|
3137 /** |
|
3138 Copies text from the specified string and converts it to upper case before |
|
3139 putting it into this descriptor, replacing any existing data. |
|
3140 |
|
3141 The length of this descriptor is set to reflect the new data. |
|
3142 |
|
3143 Conversion to upper case is implemented as appropriate to the current locale. |
|
3144 |
|
3145 This leaving variant of the standard, non-leaving descriptor method |
|
3146 differs in that this operation may cause the string descriptor's heap |
|
3147 buffer to be reallocated in order to accommodate the new data. As a |
|
3148 result, MaxLength() and Ptr() may return different values afterwards, |
|
3149 and any existing raw pointers to into the descriptor data may be |
|
3150 invalidated. |
|
3151 |
|
3152 @param aWideCharStr A wide character string. |
|
3153 |
|
3154 @leave KErrNoMemory if the underlying buffer needs to be |
|
3155 grown and there are insufficient resources to do so |
|
3156 */ |
|
3157 EXPORT_C void LString16:: CopyUCL(const wchar_t* aWideCharStr) |
|
3158 { |
|
3159 LString16::CopyUCL(reinterpret_cast<const TUint16*>(aWideCharStr)); |
|
3160 } |
|
3161 |
|
3162 /** |
|
3163 Copies text from the specified string and converts it to upper case before |
|
3164 putting it into this descriptor, replacing any existing data. |
|
3165 |
|
3166 The length of this descriptor is set to reflect the new data. |
|
3167 |
|
3168 Conversion to upper case is implemented as appropriate to the current locale. |
|
3169 |
|
3170 This leaving variant of the standard, non-leaving descriptor method |
|
3171 differs in that this operation may cause the string descriptor's heap |
|
3172 buffer to be reallocated in order to accommodate the new data. As a |
|
3173 result, MaxLength() and Ptr() may return different values afterwards, |
|
3174 and any existing raw pointers to into the descriptor data may be |
|
3175 invalidated. |
|
3176 |
|
3177 @param aZeroTerminatedString A wide zero terminated string. |
|
3178 |
|
3179 @leave KErrNoMemory if the underlying buffer needs to be |
|
3180 grown and there are insufficient resources to do so |
|
3181 */ |
|
3182 EXPORT_C void LString16:: CopyUCL(const TUint16* aZeroTerminatedString) |
|
3183 { |
|
3184 LString16::CopyUCL(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
3185 } |
|
3186 |
|
3187 /** |
|
3188 Copies text from the specified string and capitalises it before putting |
|
3189 it into this descriptor, replacing any existing data. |
|
3190 |
|
3191 The length of this descriptor is set to reflect the new data. |
|
3192 |
|
3193 Capitalisation is implemented as appropriate to the current locale. |
|
3194 |
|
3195 This leaving variant of the standard, non-leaving descriptor method |
|
3196 differs in that this operation may cause the string descriptor's heap |
|
3197 buffer to be reallocated in order to accommodate the new data. As a |
|
3198 result, MaxLength() and Ptr() may return different values afterwards, |
|
3199 and any existing raw pointers to into the descriptor data may be |
|
3200 invalidated. |
|
3201 |
|
3202 @param aWideCharStr A wide character string. |
|
3203 |
|
3204 @leave KErrNoMemory if the underlying buffer needs to be |
|
3205 grown and there are insufficient resources to do so |
|
3206 */ |
|
3207 EXPORT_C void LString16:: CopyCPL(const wchar_t* aWideCharStr) |
|
3208 { |
|
3209 LString16::CopyCPL(reinterpret_cast<const TUint16*>(aWideCharStr)); |
|
3210 } |
|
3211 |
|
3212 /** |
|
3213 Copies text from the specified string and capitalises it before putting |
|
3214 it into this descriptor, replacing any existing data. |
|
3215 |
|
3216 The length of this descriptor is set to reflect the new data. |
|
3217 |
|
3218 Capitalisation is implemented as appropriate to the current locale. |
|
3219 |
|
3220 This leaving variant of the standard, non-leaving descriptor method |
|
3221 differs in that this operation may cause the string descriptor's heap |
|
3222 buffer to be reallocated in order to accommodate the new data. As a |
|
3223 result, MaxLength() and Ptr() may return different values afterwards, |
|
3224 and any existing raw pointers to into the descriptor data may be |
|
3225 invalidated. |
|
3226 |
|
3227 @param aZeroTerminatedString A wide zero terminated string. |
|
3228 |
|
3229 @leave KErrNoMemory if the underlying buffer needs to be |
|
3230 grown and there are insufficient resources to do so |
|
3231 */ |
|
3232 EXPORT_C void LString16:: CopyCPL(const TUint16* aZeroTerminatedString) |
|
3233 { |
|
3234 LString16::CopyCPL(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
3235 } |
|
3236 /** |
|
3237 Inserts data into this descriptor. |
|
3238 |
|
3239 The length of this descriptor is changed to reflect the extra data. |
|
3240 |
|
3241 This leaving variant of the standard, non-leaving descriptor method |
|
3242 differs in that this operation may cause the string descriptor's heap |
|
3243 buffer to be reallocated in order to accommodate the new data. As a |
|
3244 result, MaxLength() and Ptr() may return different values afterwards, |
|
3245 and any existing raw pointers to into the descriptor data may be |
|
3246 invalidated. |
|
3247 |
|
3248 @param aPos The position within the data where insertion is to start. This |
|
3249 is an offset value; a zero value refers to the leftmost data |
|
3250 position. |
|
3251 |
|
3252 @param aWideCharStr A wide character string. |
|
3253 |
|
3254 @leave KErrNoMemory if the underlying buffer needs to be |
|
3255 grown and there are insufficient resources to do so |
|
3256 |
|
3257 @panic USER 10 if aPos is negative or is greater than the length of this |
|
3258 descriptor. |
|
3259 */ |
|
3260 EXPORT_C void LString16:: InsertL(TInt aPos,const wchar_t* aWideCharStr) |
|
3261 { |
|
3262 LString16::InsertL(aPos, reinterpret_cast<const TUint16*>(aWideCharStr)); |
|
3263 } |
|
3264 |
|
3265 /** |
|
3266 Inserts data into this descriptor. |
|
3267 |
|
3268 The length of this descriptor is changed to reflect the extra data. |
|
3269 |
|
3270 This leaving variant of the standard, non-leaving descriptor method |
|
3271 differs in that this operation may cause the string descriptor's heap |
|
3272 buffer to be reallocated in order to accommodate the new data. As a |
|
3273 result, MaxLength() and Ptr() may return different values afterwards, |
|
3274 and any existing raw pointers to into the descriptor data may be |
|
3275 invalidated. |
|
3276 |
|
3277 @param aPos The position within the data where insertion is to start. This |
|
3278 is an offset value; a zero value refers to the leftmost data |
|
3279 position. |
|
3280 |
|
3281 @param aZeroTerminatedString A wide null terminated string. |
|
3282 |
|
3283 @leave KErrNoMemory if the underlying buffer needs to be |
|
3284 grown and there are insufficient resources to do so |
|
3285 |
|
3286 @panic USER 10 if aPos is negative or is greater than the length of this |
|
3287 descriptor. |
|
3288 */ |
|
3289 EXPORT_C void LString16:: InsertL(TInt aPos,const TUint16* aZeroTerminatedString) |
|
3290 { |
|
3291 LString16::InsertL(aPos,TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
3292 } |
|
3293 |
|
3294 /** |
|
3295 Replaces data in this descriptor. |
|
3296 |
|
3297 The specified length can be different to the length of the replacement data. |
|
3298 The length of this descriptor changes to reflect the change of data. |
|
3299 |
|
3300 This leaving variant of the standard, non-leaving descriptor method |
|
3301 differs in that this operation may cause the string descriptor's heap |
|
3302 buffer to be reallocated in order to accommodate the new data. As a |
|
3303 result, MaxLength() and Ptr() may return different values afterwards, |
|
3304 and any existing raw pointers to into the descriptor data may be |
|
3305 invalidated. |
|
3306 |
|
3307 @param aPos The position within the data where replacement is to start. |
|
3308 This is an offset value; a zero value refers to the leftmost |
|
3309 data position. |
|
3310 |
|
3311 @param aLength The length of data to be replaced. |
|
3312 |
|
3313 @param aWideCharStr The source wide character string |
|
3314 |
|
3315 @leave KErrNoMemory if the underlying buffer needs to be |
|
3316 grown and there are insufficient resources to do so |
|
3317 |
|
3318 @panic USER 8 if aLength is negative |
|
3319 |
|
3320 @panic USER 10 if aPos is negative or is greater than the length of this |
|
3321 descriptor. |
|
3322 |
|
3323 @panic USER 16 if the length of the source descriptor aDes is negative |
|
3324 */ |
|
3325 EXPORT_C void LString16:: ReplaceL(TInt aPos,TInt aLength,const wchar_t* aWideCharStr) |
|
3326 { |
|
3327 LString16::ReplaceL(aPos,aLength,reinterpret_cast<const TUint16*>(aWideCharStr)); |
|
3328 } |
|
3329 |
|
3330 /** |
|
3331 Replaces data in this descriptor. |
|
3332 |
|
3333 The specified length can be different to the length of the replacement data. |
|
3334 The length of this descriptor changes to reflect the change of data. |
|
3335 |
|
3336 This leaving variant of the standard, non-leaving descriptor method |
|
3337 differs in that this operation may cause the string descriptor's heap |
|
3338 buffer to be reallocated in order to accommodate the new data. As a |
|
3339 result, MaxLength() and Ptr() may return different values afterwards, |
|
3340 and any existing raw pointers to into the descriptor data may be |
|
3341 invalidated. |
|
3342 |
|
3343 @param aPos The position within the data where replacement is to start. |
|
3344 This is an offset value; a zero value refers to the leftmost |
|
3345 data position. |
|
3346 |
|
3347 @param aLength The length of data to be replaced. |
|
3348 |
|
3349 @param aZeroTerminatedString The source wide null terminated character string |
|
3350 |
|
3351 @leave KErrNoMemory if the underlying buffer needs to be |
|
3352 grown and there are insufficient resources to do so |
|
3353 |
|
3354 @panic USER 8 if aLength is negative |
|
3355 |
|
3356 @panic USER 10 if aPos is negative or is greater than the length of this |
|
3357 descriptor. |
|
3358 |
|
3359 @panic USER 16 if the length of the source descriptor aDes is negative |
|
3360 */ |
|
3361 EXPORT_C void LString16:: ReplaceL(TInt aPos,TInt aLength,const TUint16* aZeroTerminatedString) |
|
3362 { |
|
3363 LString16::ReplaceL(aPos,aLength,TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
3364 } |
|
3365 |
|
3366 /** |
|
3367 Copies data into this descriptor and justifies it, replacing any existing data. |
|
3368 |
|
3369 The length of this descriptor is set to reflect the new data. |
|
3370 |
|
3371 The target area is considered to be an area of specified width positioned at |
|
3372 the beginning of this descriptor's data area. Source data is copied into, and |
|
3373 aligned within this target area according to the specified alignment |
|
3374 instruction. |
|
3375 |
|
3376 If the length of the target area is larger than the length of the source, then |
|
3377 spare space within the target area is padded with the fill character. |
|
3378 |
|
3379 This leaving variant of the standard, non-leaving descriptor method |
|
3380 differs in that this operation may cause the string descriptor's heap |
|
3381 buffer to be reallocated in order to accommodate the new data. As a |
|
3382 result, MaxLength() and Ptr() may return different values afterwards, |
|
3383 and any existing raw pointers to into the descriptor data may be |
|
3384 invalidated. |
|
3385 |
|
3386 @param aWideCharStr A wide character string containing the source data. |
|
3387 The length of the data to be copied is the smaller of: |
|
3388 the length of the source descriptor, and |
|
3389 the width of the target area (only if this is not the |
|
3390 explicit negative value KDefaultJustifyWidth). |
|
3391 |
|
3392 @param aWidth The width of the target area. If this has the specific |
|
3393 negative value KDefaultJustifyWidth, then the width is |
|
3394 re-set to the length of the data source. |
|
3395 |
|
3396 @param aAlignment The alignment of the data within the target area |
|
3397 |
|
3398 @param aFill The fill character used to pad the target area. |
|
3399 |
|
3400 @leave KErrNoMemory if the underlying buffer needs to be |
|
3401 grown and there are insufficient resources to do so |
|
3402 |
|
3403 @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. |
|
3404 */ |
|
3405 EXPORT_C void LString16:: JustifyL(const wchar_t* aWideCharStr,TInt aWidth,TAlign anAlignment,TChar aFill) |
|
3406 { |
|
3407 LString16::JustifyL(reinterpret_cast<const TUint16*>(aWideCharStr),aWidth,anAlignment,aFill); |
|
3408 } |
|
3409 |
|
3410 /** |
|
3411 Copies data into this descriptor and justifies it, replacing any existing data. |
|
3412 |
|
3413 The length of this descriptor is set to reflect the new data. |
|
3414 |
|
3415 The target area is considered to be an area of specified width positioned at |
|
3416 the beginning of this descriptor's data area. Source data is copied into, and |
|
3417 aligned within this target area according to the specified alignment |
|
3418 instruction. |
|
3419 |
|
3420 If the length of the target area is larger than the length of the source, then |
|
3421 spare space within the target area is padded with the fill character. |
|
3422 |
|
3423 This leaving variant of the standard, non-leaving descriptor method |
|
3424 differs in that this operation may cause the string descriptor's heap |
|
3425 buffer to be reallocated in order to accommodate the new data. As a |
|
3426 result, MaxLength() and Ptr() may return different values afterwards, |
|
3427 and any existing raw pointers to into the descriptor data may be |
|
3428 invalidated. |
|
3429 |
|
3430 @param aWideCharStr A wide character string containing the source data. |
|
3431 The length of the data to be copied is the smaller of: |
|
3432 the length of the source descriptor, and |
|
3433 the width of the target area (only if this is not the |
|
3434 explicit negative value KDefaultJustifyWidth). |
|
3435 |
|
3436 @param aWidth The width of the target area. If this has the specific |
|
3437 negative value KDefaultJustifyWidth, then the width is |
|
3438 re-set to the length of the data source. |
|
3439 |
|
3440 @param aAlignment The alignment of the data within the target area |
|
3441 |
|
3442 @param aFill The fill character used to pad the target area. |
|
3443 |
|
3444 @leave KErrNoMemory if the underlying buffer needs to be |
|
3445 grown and there are insufficient resources to do so |
|
3446 |
|
3447 @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. |
|
3448 */ |
|
3449 EXPORT_C void LString16:: JustifyL(const TUint16* aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill) |
|
3450 { |
|
3451 LString16::JustifyL(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)),aWidth,anAlignment,aFill); |
|
3452 } |
|
3453 |
|
3454 /** |
|
3455 Appends data onto the end of this descriptor's data and justifies it. |
|
3456 |
|
3457 The source of the appended data is a memory location. |
|
3458 |
|
3459 The target area is considered to be an area of specified width, immediately |
|
3460 following this descriptor's existing data. Source data is copied into, and |
|
3461 aligned within, this target area according to the specified alignment instruction. |
|
3462 |
|
3463 If the length of the target area is larger than the length of the source, |
|
3464 then spare space within the target area is padded with the fill character. |
|
3465 |
|
3466 This leaving variant of the standard, non-leaving descriptor method |
|
3467 differs in that this operation may cause the string descriptor's heap |
|
3468 buffer to be reallocated in order to accommodate the new data. As a |
|
3469 result, MaxLength() and Ptr() may return different values afterwards, |
|
3470 and any existing raw pointers to into the descriptor data may be |
|
3471 invalidated. |
|
3472 |
|
3473 @param aString A pointer to a source memory location. |
|
3474 |
|
3475 @param aLength The length of data to be copied. If this is greater than the |
|
3476 width of the target area, then the length of data copied is |
|
3477 limited to the width. |
|
3478 |
|
3479 @param aWidth The width of the target area. If this has the specific negative |
|
3480 value KDefaultJustifyWidth, then the width is |
|
3481 re-set to the length of the data source. |
|
3482 |
|
3483 @param aAlignment The alignment of the data within the target area. |
|
3484 |
|
3485 @param aFill The fill character used to pad the target area. |
|
3486 |
|
3487 @leave KErrNoMemory if the underlying buffer needs to be |
|
3488 grown and there are insufficient resources to do so |
|
3489 |
|
3490 @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. |
|
3491 |
|
3492 @panic USER 17 if aLength is negative. |
|
3493 */ |
|
3494 EXPORT_C void LString16:: AppendJustifyL(const wchar_t* aWideCharStr,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill) |
|
3495 { |
|
3496 LString16::AppendJustifyL(reinterpret_cast<const TUint16*>(aWideCharStr),aLength, aWidth,anAlignment,aFill); |
|
3497 } |
|
3498 //eof |