|
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 Aligns the supplied capacity to the nearest growth factor |
|
23 |
|
24 For performance reasons the growth factor, KDefaultExpandSizeShift, |
|
25 is expressed as an exponent of 2 so shifting can be used to achieve the |
|
26 alignment. |
|
27 |
|
28 a KDefaultExpandSizeShift value of 4 is equivalent to 16; |
|
29 giving newCapacity = ((newCapacity / 16) + 1) * 16 |
|
30 |
|
31 @param aNewCapacity The size to be aligned |
|
32 |
|
33 @return The new, aligned capacity |
|
34 */ |
|
35 static inline TInt AlignCapacity(TInt aNewCapacity) |
|
36 { |
|
37 const TUint KDefaultExpandSizeShift = 4; |
|
38 |
|
39 return (TInt)((((TUint)aNewCapacity >> KDefaultExpandSizeShift) + 1) << KDefaultExpandSizeShift); |
|
40 } |
|
41 |
|
42 /** |
|
43 Guarantees that MaxLength() is greater than or equal to the supplied |
|
44 capacity, reallocating the supplied capacity if necessary. |
|
45 |
|
46 The actual value of MaxLength() after a call may differ from the exact |
|
47 value requested, but if it does differ it will always be greater. This |
|
48 flexibility allows the implementation to manage heap buffers more |
|
49 efficiently. |
|
50 |
|
51 The string descriptor's heap buffer may be reallocated in order to |
|
52 accommodate the new size. As a |
|
53 result, MaxLength() and Ptr() may return different values afterwards, |
|
54 and any existing raw pointers to into the descriptor data may be |
|
55 invalidated. |
|
56 |
|
57 @param aMinRequiredCapacity The minimum value of MaxLength() required |
|
58 |
|
59 @leave KErrNoMemory if the underlying buffer needs to be |
|
60 grown and there are insufficient resources to do so |
|
61 */ |
|
62 void LString8::ReserveL(TInt aMinRequiredCapacity) |
|
63 { |
|
64 if (MaxLength() < aMinRequiredCapacity) |
|
65 { |
|
66 ReAllocL(AlignCapacity(aMinRequiredCapacity)); |
|
67 } |
|
68 } |
|
69 |
|
70 |
|
71 /** |
|
72 Guarantees that MaxLength() is greater than or equal to the supplied |
|
73 integer parameter, growing the underlying heap buffer if necessary. |
|
74 |
|
75 The growth is exponential; maxLength *= 1.5 |
|
76 This is reported to give an amortised complexity of O(n) when adding |
|
77 n characters. |
|
78 If the required capacity is larger than the expanded size then the |
|
79 required capacity is used instead. |
|
80 |
|
81 The actual value of MaxLength() after a call may differ from the exact |
|
82 value requested, but if it does differ it will always be greater. This |
|
83 flexibility allows the implementation to manage heap buffers more |
|
84 efficiently. |
|
85 |
|
86 @param aRequiredCapacity The minimum value of MaxLength() required |
|
87 |
|
88 @leave KErrNoMemory if the underlying buffer needs to be |
|
89 grown and there are insufficient resources to do so |
|
90 */ |
|
91 void LString8::ReserveCapacityGrowExponentialL(TInt aRequiredCapacity) |
|
92 { |
|
93 //work in unsigned int for the appropriate shift operation |
|
94 TUint max_length = MaxLength(); |
|
95 TUint requiredCapacity = aRequiredCapacity; |
|
96 |
|
97 if (max_length < requiredCapacity) |
|
98 { |
|
99 // max_length *= 3/2; |
|
100 max_length = (max_length + (max_length << 1)) >> 1; |
|
101 |
|
102 // take the bigger of the extended buffer or the required capactiy |
|
103 ReAllocL(AlignCapacity((TInt)(max_length > requiredCapacity ? max_length : requiredCapacity))); |
|
104 } |
|
105 } |
|
106 |
|
107 /** |
|
108 Guarantees that free space in the buffer greater than or equal the |
|
109 supplied integer parameter, growing the underlying heap buffer |
|
110 if necessary. |
|
111 |
|
112 @param aRequiredEmptySpace The minimum value of free space required |
|
113 |
|
114 @leave KErrNoMemory if the underlying buffer needs to be |
|
115 grown and there are insufficient resources to do so |
|
116 */ |
|
117 void LString8::ReserveFreeCapacityGrowExponentialL(TInt aRequiredEmptySpace) |
|
118 { |
|
119 ReserveCapacityGrowExponentialL(Length() + aRequiredEmptySpace); |
|
120 } |
|
121 |
|
122 /** |
|
123 Grows the underlying buffer using the exponential growth |
|
124 function. Guarantees that MaxLength() is greater than or |
|
125 equal to 1.5 * the current MaxLength. |
|
126 |
|
127 |
|
128 @leave KErrNoMemory if the underlying buffer needs to be |
|
129 grown and there are insufficient resources to do so |
|
130 */ |
|
131 void LString8::ReserveCapacityGrowExponentialL() |
|
132 { |
|
133 ReserveCapacityGrowExponentialL(MaxLength() + 1); |
|
134 } |
|
135 |
|
136 |
|
137 /** |
|
138 Default constructor. |
|
139 |
|
140 Constructs a zero-length 8-bit resizable string descriptor. |
|
141 |
|
142 Note that the resulting object owns no allocated memory yet. This |
|
143 default constructor never leaves. |
|
144 */ |
|
145 EXPORT_C LString8::LString8() |
|
146 : iReserved(0) |
|
147 { |
|
148 } |
|
149 |
|
150 /** |
|
151 Destructor. |
|
152 |
|
153 Frees any heap-allocated resources owned by this string descriptor. It |
|
154 is safe to rely on this destructor to perform all necessary cleanup; |
|
155 it is not necessary use the cleanup stack or to call Close() manually. |
|
156 |
|
157 @see RBuf8::Close |
|
158 */ |
|
159 EXPORT_C LString8::~LString8() |
|
160 { |
|
161 RBuf8::Close(); |
|
162 } |
|
163 |
|
164 /** |
|
165 Constructor to create a 8-bit resizable string descriptor with an |
|
166 initial capacity. |
|
167 |
|
168 The function allocates sufficient memory to contain descriptor data up to |
|
169 the specified initial maximum length. |
|
170 |
|
171 The current length of the descriptor is set to zero. The maximum length of |
|
172 the descriptor is set to the specified value. |
|
173 |
|
174 @param aMaxLength The maximum length of the descriptor. |
|
175 |
|
176 @leave KErrNoMemory If there is insufficient memory. |
|
177 |
|
178 @see RBuf8::CreateL |
|
179 */ |
|
180 EXPORT_C LString8::LString8(TInt aMaxLength) |
|
181 : iReserved(0) |
|
182 { |
|
183 RBuf8::CreateL(aMaxLength); |
|
184 } |
|
185 |
|
186 /** |
|
187 Constructor to create a 8-bit resizable string descriptor from a |
|
188 pre-allocated heap descriptor. |
|
189 |
|
190 Transfers ownership of the specified heap descriptor to this object. |
|
191 |
|
192 @param aHBuf The heap descriptor to be transferred to this object. |
|
193 This pointer can be NULL, which means that a zero length |
|
194 8-bit resizable string descriptor is created. |
|
195 |
|
196 @see RBuf8::RBuf8(HBufC8*) |
|
197 */ |
|
198 EXPORT_C LString8::LString8(HBufC8* aHBuf) |
|
199 : iReserved(0) |
|
200 { |
|
201 if (aHBuf) |
|
202 RBuf8::Assign (aHBuf); |
|
203 } |
|
204 |
|
205 /** |
|
206 Constructor to create a 8-bit resizable string descriptor from a |
|
207 pre-allocated raw heap buffer. |
|
208 |
|
209 The allocated memory forms the buffer for this string descriptor. The |
|
210 current length of the descriptor is set to zero. |
|
211 |
|
212 @param aHeapCell The allocated memory to be assigned to this object. This |
|
213 pointer can be NULL, which means that a zero length 8-bit |
|
214 resizable buffer descriptor is created. |
|
215 @param aMaxLength The maximum length of the constructed string descriptor. |
|
216 |
|
217 @panic USER 8 If the specified maximum length is greater then the size of |
|
218 the allocated heap cell, or the specified maximum length |
|
219 is NOT zero when the pointer to the heap cell is NULL. |
|
220 |
|
221 @see RBuf8::Assign() |
|
222 */ |
|
223 EXPORT_C LString8::LString8(TUint8* aHeapCell,TInt aMaxLength) |
|
224 : iReserved(0) |
|
225 { |
|
226 RBuf8::Assign(aHeapCell, aMaxLength); |
|
227 } |
|
228 |
|
229 /** |
|
230 Constructor to create a 8-bit resizable string descriptor from a |
|
231 pre-allocated raw heap buffer. |
|
232 |
|
233 The allocated memory forms the buffer for this string descriptor. The |
|
234 current length of the descriptor is set to the value of the second |
|
235 parameter. |
|
236 |
|
237 @param aHeapCell The allocated memory to be assigned to this object. |
|
238 @param aLength The length of the resulting string descriptor. |
|
239 @param aMaxLength The maximum length of the resulting string descriptor. |
|
240 |
|
241 @panic USER 8 If the specified maximum length is greater then the size of |
|
242 the allocated heap cell, or the specified length is greater then |
|
243 the specified maximum length, or the specified maximum length |
|
244 is NOT zero when the pointer to the heap cell is NULL. |
|
245 |
|
246 @see RBuf8::Assign() |
|
247 */ |
|
248 EXPORT_C LString8::LString8(TUint8* aHeapCell,TInt aLength,TInt aMaxLength) |
|
249 : iReserved(0) |
|
250 { |
|
251 RBuf8::Assign(aHeapCell, aLength, aMaxLength); |
|
252 } |
|
253 |
|
254 /** |
|
255 Constructor to create a 8-bit resizable string descriptor to contain |
|
256 a copy of the specified (source) descriptor, or leave on failure. |
|
257 |
|
258 The constructor allocates sufficient memory so that this string |
|
259 descriptor's maximum length is the same as the length of the source |
|
260 descriptor. Both the current length and the maximum length of this |
|
261 string descriptor are set to the length of the source descriptor. |
|
262 |
|
263 The data contained in the source descriptor is copied into this string |
|
264 descriptor. |
|
265 |
|
266 @param aDes Source descriptor to be copied into this object. |
|
267 |
|
268 @leave KErrNoMemory If there is insufficient memory. |
|
269 |
|
270 @see RBuf8::CreateL() |
|
271 */ |
|
272 EXPORT_C LString8::LString8(const TDesC8& aDes) |
|
273 : iReserved(0) |
|
274 { |
|
275 RBuf8::CreateL(aDes); |
|
276 } |
|
277 |
|
278 /** |
|
279 Copies data into this 8-bit string descriptor, replacing any existing |
|
280 data, and expanding its heap buffer to accommodate if necessary. |
|
281 |
|
282 The length of this descriptor is set to reflect the new data. |
|
283 |
|
284 This operation may cause the target string descriptor's heap buffer to |
|
285 be reallocated in order to accommodate the new data. As a result, |
|
286 MaxLength() and Ptr() may return different values afterwards, and any |
|
287 existing raw pointers to into the descriptor data may be invalidated. |
|
288 |
|
289 Note that the automatic resizing performed is a change to the |
|
290 functionality of this operation compared to other descriptor |
|
291 classes. This change is only active on objects directly declared |
|
292 LString8; when LString8 instances are instead manipulated via |
|
293 references to TDes8 or TDesC8, the standard (non-resizing, panicing) |
|
294 variant is invoked. |
|
295 |
|
296 @param aDes A 8-bit non-modifiable descriptor. |
|
297 |
|
298 @return A reference to this 8-bit string descriptor. |
|
299 |
|
300 @@leave KErrNoMemory If the heap buffer of the string descriptor being |
|
301 assigned to needs to be expanded, but there is |
|
302 insufficient memory to do so |
|
303 |
|
304 @see LString8::CopyL |
|
305 */ |
|
306 EXPORT_C LString8& LString8::operator=(const TDesC8& aDes) |
|
307 { |
|
308 CopyL(aDes); |
|
309 return *this; |
|
310 } |
|
311 |
|
312 |
|
313 /** |
|
314 Transfers ownership of the specified 8-bit descriptor to this object. |
|
315 |
|
316 @param aBuf The source 8-bit buffer. The ownership of this |
|
317 object's buffer is to be transferred. |
|
318 |
|
319 @see Assign() |
|
320 */ |
|
321 EXPORT_C LString8& LString8::operator=(HBufC8* aBuf) |
|
322 { |
|
323 Assign(aBuf); |
|
324 return *this; |
|
325 } |
|
326 |
|
327 |
|
328 /** |
|
329 Copies data into this 8-bit string descriptor, replacing any existing |
|
330 data, and expanding its heap buffer to accommodate if necessary. |
|
331 |
|
332 The length of this descriptor is set to reflect the new data. |
|
333 |
|
334 This leaving variant of the standard, non-leaving descriptor method |
|
335 differs in that this operation may cause the string descriptor's heap |
|
336 buffer to be reallocated in order to accommodate the new data. As a |
|
337 result, MaxLength() and Ptr() may return different values afterwards, |
|
338 and any existing raw pointers to into the descriptor data may be |
|
339 invalidated. |
|
340 |
|
341 @param aDes A 8-bit non-modifiable descriptor. |
|
342 |
|
343 @leave KErrNoMemory If the heap buffer of the string descriptor being |
|
344 assigned to needs to be expanded, but there is |
|
345 insufficient memory to do so |
|
346 |
|
347 @see LString8::operator= |
|
348 @see TDes8::Copy |
|
349 */ |
|
350 EXPORT_C void LString8::CopyL(const TDesC8& aDes) |
|
351 { |
|
352 ReserveL(aDes.Length()); |
|
353 RBuf8::Copy(aDes); |
|
354 } |
|
355 |
|
356 /** |
|
357 Copies data into this 8-bit string descriptor, replacing any existing |
|
358 data, and expanding its heap buffer to accommodate if necessary. |
|
359 |
|
360 The length of this descriptor is set to reflect the new data. |
|
361 |
|
362 This leaving variant of the standard, non-leaving descriptor method |
|
363 differs in that this operation may cause the string descriptor's heap |
|
364 buffer to be reallocated in order to accommodate the new data. As a |
|
365 result, MaxLength() and Ptr() may return different values afterwards, |
|
366 and any existing raw pointers to into the descriptor data may be |
|
367 invalidated. |
|
368 |
|
369 @param aDes A 16-bit non-modifiable descriptor.A 16-bit non-modifiable descriptor. |
|
370 Each double-byte value can |
|
371 only be copied into the corresponding single byte when the |
|
372 double-byte value is less than decimal 256. A double-byte value of |
|
373 256 or greater cannot be copied and the corresponding single byte |
|
374 is set to a value of decimal 1. |
|
375 |
|
376 @leave KErrNoMemory If the heap buffer of the string descriptor being |
|
377 assigned to needs to be expanded, but there is |
|
378 insufficient memory to do so |
|
379 |
|
380 @see TDes8::Copy |
|
381 */ |
|
382 EXPORT_C void LString8::CopyL(const TDesC16& aDes) |
|
383 { |
|
384 ReserveL(aDes.Length()); |
|
385 RBuf8::Copy(aDes); |
|
386 } |
|
387 |
|
388 /** |
|
389 Copy constructor to create a 8-bit resizable string descriptor to |
|
390 contain a copy of the specified (source) string descriptor's data, or |
|
391 leave on failure. |
|
392 |
|
393 The constructor allocates sufficient memory so that this string |
|
394 descriptor's maximum length is the same as the length of the source |
|
395 string descriptor. Both the current length and the maximum length of |
|
396 this string descriptor are set to the length of the source descriptor. |
|
397 |
|
398 The data contained in the source string descriptor is copied into this |
|
399 string descriptor. |
|
400 |
|
401 @param aDes Source string descriptor to be copied into this object. |
|
402 |
|
403 @leave KErrNoMemory If there is insufficient memory. |
|
404 |
|
405 @see RBuf8::CreateL() |
|
406 */ |
|
407 EXPORT_C LString8::LString8(const LString8& aDes) |
|
408 : iReserved(0) |
|
409 { |
|
410 RBuf8::CreateL(aDes); |
|
411 } |
|
412 |
|
413 |
|
414 /** |
|
415 Copies data into this 8-bit string descriptor, replacing any existing |
|
416 data, and expanding its heap buffer to accommodate if necessary. |
|
417 |
|
418 The length of this descriptor is set to reflect the new data. |
|
419 |
|
420 This operation may cause the target string descriptor's heap buffer to |
|
421 be reallocated in order to accommodate the new data. As a result, |
|
422 MaxLength() and Ptr() may return different values afterwards, and any |
|
423 existing raw pointers to into the descriptor data may be invalidated. |
|
424 |
|
425 Note that the automatic resizing performed is a change to the |
|
426 functionality of this operation compared to other descriptor |
|
427 classes. This change is only active on objects directly declared |
|
428 LString8; when LString8 instances are instead manipulated via |
|
429 references to TDes8 or TDesC8, the standard (non-resizing, panicing) |
|
430 variant is invoked. |
|
431 |
|
432 @param aDes A 8-bit string descriptor. |
|
433 |
|
434 @return A reference to this 8-bit string descriptor. |
|
435 |
|
436 @leave KErrNoMemory If the heap buffer of the string descriptor being |
|
437 assigned to needs to be expanded, but there is |
|
438 insufficient memory to do so |
|
439 |
|
440 @see LString8::CopyL |
|
441 */ |
|
442 EXPORT_C LString8& LString8::operator=(const LString8& aDes) |
|
443 { |
|
444 CopyL(aDes); |
|
445 return *this; |
|
446 } |
|
447 |
|
448 /** |
|
449 Constructor to create a 8-bit resizable string descriptor containing |
|
450 a copy of the specified (source) zero-terminated string data, or leave |
|
451 on failure. |
|
452 |
|
453 The constructor allocates sufficient memory so that this string |
|
454 descriptor's maximum length is the same as the length of the source |
|
455 string. Both the current length and the maximum length of this string |
|
456 descriptor are set to the length of the source string. |
|
457 |
|
458 The data contained in the source string is copied into this string |
|
459 descriptor. The zero terminator is not copied. |
|
460 |
|
461 @param aZeroTerminatedString A pointer to a zero-terminated string |
|
462 |
|
463 @leave KErrNoMemory If there is insufficient memory. |
|
464 |
|
465 @see LString8::CopyL |
|
466 */ |
|
467 EXPORT_C LString8::LString8(const TUint8* aZeroTerminatedString) |
|
468 : iReserved(0) |
|
469 { |
|
470 CopyL(aZeroTerminatedString); |
|
471 } |
|
472 |
|
473 /** |
|
474 Copies data into this 8-bit string descriptor, replacing any existing |
|
475 data, and expanding its heap buffer to accommodate if necessary. |
|
476 |
|
477 The length of this descriptor is set to reflect the new data. |
|
478 |
|
479 This operation may cause the target string descriptor's heap buffer to |
|
480 be reallocated in order to accommodate the new data. As a result, |
|
481 MaxLength() and Ptr() may return different values afterwards, and any |
|
482 existing raw pointers to into the descriptor data may be invalidated. |
|
483 |
|
484 Note that the automatic resizing performed is a change to the |
|
485 functionality of this operation compared to other descriptor |
|
486 classes. This change is only active on objects directly declared |
|
487 LString8; when LString8 instances are instead manipulated via |
|
488 references to TDes8 or TDesC8, the standard (non-resizing, panicing) |
|
489 variant is invoked. |
|
490 |
|
491 @param aZeroTerminatedString A pointer to a zero-terminated string |
|
492 |
|
493 @return A reference to this 8-bit string descriptor. |
|
494 |
|
495 @leave KErrNoMemory If the heap buffer of the string descriptor being |
|
496 assigned to needs to be expanded, but there is |
|
497 insufficient memory to do so |
|
498 |
|
499 @see LString8::CopyL |
|
500 */ |
|
501 EXPORT_C LString8& LString8::operator=(const TUint8* aZeroTerminatedString) |
|
502 { |
|
503 CopyL(aZeroTerminatedString); |
|
504 return *this; |
|
505 } |
|
506 |
|
507 /** |
|
508 Copies data into this 8-bit string descriptor, replacing any existing |
|
509 data, and expanding its heap buffer to accommodate if necessary. |
|
510 |
|
511 The length of this descriptor is set to reflect the new data. |
|
512 |
|
513 This leaving variant of the standard, non-leaving descriptor method |
|
514 differs in that this operation may cause the string descriptor's heap |
|
515 buffer to be reallocated in order to accommodate the new data. As a |
|
516 result, MaxLength() and Ptr() may return different values afterwards, |
|
517 and any existing raw pointers to into the descriptor data may be |
|
518 invalidated. |
|
519 |
|
520 @param aZeroTerminatedString A pointer to a zero-terminated string |
|
521 |
|
522 @leave KErrNoMemory If the heap buffer of the string descriptor being |
|
523 assigned to needs to be expanded, but there is |
|
524 insufficient memory to do so |
|
525 |
|
526 @see LString8::operator= |
|
527 @see TDes8::Copy |
|
528 */ |
|
529 EXPORT_C void LString8::CopyL(const TUint8* aZeroTerminatedString) |
|
530 { |
|
531 ReserveL(User::StringLength(aZeroTerminatedString)); |
|
532 RBuf8::Copy(aZeroTerminatedString); |
|
533 } |
|
534 |
|
535 /** |
|
536 Copies data into this 8-bit string descriptor, replacing any existing |
|
537 data, and expanding its heap buffer to accommodate if necessary. |
|
538 |
|
539 The length of this descriptor is set according to the second |
|
540 parameter. |
|
541 |
|
542 This leaving variant of the standard, non-leaving descriptor method |
|
543 differs in that this operation may cause the string descriptor's heap |
|
544 buffer to be reallocated in order to accommodate the new data. As a |
|
545 result, MaxLength() and Ptr() may return different values afterwards, |
|
546 and any existing raw pointers to into the descriptor data may be |
|
547 invalidated. |
|
548 |
|
549 @param aBuf The start address of data to be copied. |
|
550 @param aLength The length of data to be copied. |
|
551 |
|
552 @leave KErrNoMemory If the heap buffer of the string descriptor being |
|
553 assigned to needs to be expanded, but there is |
|
554 insufficient memory to do so |
|
555 |
|
556 @panic USER 11 if aLength is negative. |
|
557 |
|
558 @see TDes8::Copy |
|
559 */ |
|
560 EXPORT_C void LString8::CopyL(const TUint8* aBuf,TInt aLength) |
|
561 { |
|
562 ReserveL(aLength); |
|
563 RBuf8::Copy(aBuf, aLength); |
|
564 } |
|
565 |
|
566 |
|
567 /** |
|
568 Sets the length of the data represented by the string descriptor to |
|
569 the specified value. |
|
570 |
|
571 This leaving variant of the standard, non-leaving descriptor method |
|
572 differs in that this operation may cause the string descriptor's heap |
|
573 buffer to be reallocated in order to accommodate the new data. As a |
|
574 result, MaxLength() and Ptr() may return different values afterwards, |
|
575 and any existing raw pointers to into the descriptor data may be |
|
576 invalidated. |
|
577 |
|
578 @param aLength The new length of the descriptor. |
|
579 |
|
580 @leave KErrNoMemory if the underlying buffer needs to be |
|
581 grown and there are insufficient resources to do so |
|
582 |
|
583 @panic USER 11 if aLength is negative |
|
584 */ |
|
585 EXPORT_C void LString8::SetLengthL(TInt aLength) |
|
586 { |
|
587 ReserveL(aLength); |
|
588 RBuf8::SetLength(aLength); |
|
589 } |
|
590 |
|
591 |
|
592 /** |
|
593 Sets the storage space allocated to this descriptor to the specified |
|
594 value by growing or compressing its buffer size. |
|
595 |
|
596 If the current length of the descriptor is greater than the specified |
|
597 max length, length is truncated to max length. |
|
598 |
|
599 This leaving variant of the standard, non-leaving descriptor method |
|
600 differs in that this operation may cause the string descriptor's heap |
|
601 buffer to be reallocated in order to accommodate the new data. As a |
|
602 result, MaxLength() and Ptr() may return different values afterwards, |
|
603 and any existing raw pointers to into the descriptor data may be |
|
604 invalidated. |
|
605 |
|
606 @param aMaxLength The new maximum length of the descriptor. |
|
607 |
|
608 @leave KErrNoMemory if the the buffer needs to be |
|
609 reallocated and there are insufficient resources to do so |
|
610 |
|
611 @panic USER 11 if aLength is negative |
|
612 */ |
|
613 EXPORT_C void LString8::SetMaxLengthL(TInt aMaxLength) |
|
614 { |
|
615 if (MaxLength() == aMaxLength) |
|
616 { |
|
617 return; |
|
618 } |
|
619 |
|
620 if (Length() > aMaxLength) |
|
621 { |
|
622 // truncate the current length |
|
623 RBuf8::SetLength(aMaxLength); |
|
624 } |
|
625 |
|
626 ReAllocL(aMaxLength); |
|
627 } |
|
628 |
|
629 |
|
630 /** |
|
631 Ensures that the remaining unused space is more than the supplied value. |
|
632 |
|
633 May reallocate a larger storage space to meet the requirement. |
|
634 As a result MaxLength() and Ptr() may return different values afterwards, |
|
635 and any existing raw pointers to into the descriptor data may be |
|
636 invalidated. |
|
637 |
|
638 Typically, you use this method to reserve a known amount of required space |
|
639 in one go instead of relying on the automatic growth pattern. |
|
640 |
|
641 @param aExtraSpaceLength The extra space required. |
|
642 |
|
643 @leave KErrNoMemory if the the buffer needs to be |
|
644 reallocated and there are insufficient resources to do so. |
|
645 |
|
646 @panic USER 11 if aLength is negative |
|
647 */ |
|
648 EXPORT_C void LString8::ReserveFreeCapacityL(TInt aExtraSpaceLength) |
|
649 { |
|
650 ReserveL(Length() + aExtraSpaceLength); |
|
651 } |
|
652 |
|
653 |
|
654 /** |
|
655 Re-initialises the descriptor destroying its payload |
|
656 |
|
657 */ |
|
658 EXPORT_C void LString8::Reset() |
|
659 { |
|
660 RBuf8::Close(); |
|
661 } |
|
662 |
|
663 |
|
664 /** |
|
665 Re-allocates a smaller descriptor buffer space to the current |
|
666 descriptor length |
|
667 |
|
668 This may cause the string descriptor's heap buffer to be reallocated |
|
669 in order to accommodate the new data. As a |
|
670 result, MaxLength() and Ptr() may return different values afterwards, |
|
671 and any existing raw pointers to into the descriptor data may be |
|
672 invalidated. |
|
673 |
|
674 If there is insufficient memory to re-allocate the buffer then the |
|
675 descriptor left unchanged |
|
676 */ |
|
677 EXPORT_C void LString8::Compress() |
|
678 { |
|
679 TInt length = Length(); |
|
680 if (MaxLength() > length) |
|
681 { |
|
682 //coverity[checked_return] |
|
683 /*Check for return value from realloc is not needed because neither can |
|
684 * maxlength be negative or length be less than the existing data length |
|
685 */ |
|
686 ReAlloc(length); |
|
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 LString8::operator+= |
|
709 */ |
|
710 EXPORT_C void LString8::AppendL(TChar aChar) |
|
711 { |
|
712 ReserveFreeCapacityGrowExponentialL(1); |
|
713 RBuf8::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 LString8::AppendL |
|
735 */ |
|
736 EXPORT_C LString8& LString8::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 8-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 LString8::AppendL(const TDesC8& aDes) |
|
760 { |
|
761 ReserveFreeCapacityGrowExponentialL(aDes.Length()); |
|
762 RBuf8::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 8-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 LString8::AppendL |
|
783 */ |
|
784 EXPORT_C LString8& LString8::operator+=(const TDesC8& 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 LString8::AppendL(const TUint8* aBuf,TInt aLength) |
|
811 { |
|
812 ReserveFreeCapacityGrowExponentialL(aLength); |
|
813 RBuf8::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 LString8::FillL(TChar aChar,TInt aLength) |
|
840 { |
|
841 ReserveL(aLength); |
|
842 RBuf8::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 LString8::FillZL(TInt aLength) |
|
868 { |
|
869 ReserveL(aLength); |
|
870 RBuf8::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 LString8::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 LString8::AppendNumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth) |
|
946 { |
|
947 ReserveFreeCapacityGrowExponentialL(aWidth); |
|
948 RBuf8::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 TUint8 *LString8::PtrZL() |
|
971 { |
|
972 ReserveFreeCapacityL(1); |
|
973 return RBuf8::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 8-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 LString8::CopyFL(const TDesC8& aDes) |
|
1001 { |
|
1002 ReserveL(aDes.Length()); |
|
1003 RBuf8::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 8-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 LString8::CopyCL(const TDesC8& aDes) |
|
1025 { |
|
1026 ReserveL(aDes.Length()); |
|
1027 RBuf8::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 8-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 LString8::CopyLCL(const TDesC8& aDes) |
|
1051 { |
|
1052 ReserveL(aDes.Length()); |
|
1053 RBuf8::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 8-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 LString8::CopyUCL(const TDesC8& aDes) |
|
1077 { |
|
1078 ReserveL(aDes.Length()); |
|
1079 RBuf8::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 8-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 LString8::CopyCPL(const TDesC8& aDes) |
|
1103 { |
|
1104 ReserveL(aDes.Length()); |
|
1105 RBuf8::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 LString8::AppendFillL(TChar aChar,TInt aLength) |
|
1130 { |
|
1131 ReserveFreeCapacityGrowExponentialL(aLength); |
|
1132 RBuf8::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 LString8::ZeroTerminateL() |
|
1152 { |
|
1153 ReserveFreeCapacityL(1); |
|
1154 RBuf8::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 LString8, then the function |
|
1169 raises a USER 11 panic. The target LString8 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 8-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 LString8 |
|
1187 */ |
|
1188 EXPORT_C void LString8::SwapL(TDes8& aDes) |
|
1189 { |
|
1190 ReserveL(aDes.Length()); |
|
1191 TDes8::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 8-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 LString8::SwapL(LString8& aDes) |
|
1216 { |
|
1217 this->ReserveL(aDes.Length()); |
|
1218 aDes.ReserveL(this->Length()); |
|
1219 TDes8::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 8-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 LString8::InsertL(TInt aPos,const TDesC8& aDes) |
|
1248 { |
|
1249 ReserveFreeCapacityGrowExponentialL(aDes.Length()); |
|
1250 RBuf8::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 8-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 LString8::ReplaceL(TInt aPos,TInt aLength,const TDesC8& aDes) |
|
1286 { |
|
1287 TInt delta = aDes.Length() - aLength; |
|
1288 if (delta > 0) |
|
1289 { |
|
1290 ReserveFreeCapacityGrowExponentialL(delta); |
|
1291 } |
|
1292 RBuf8::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 8-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 LString8::JustifyL(const TDesC8& aDes,TInt aWidth,TAlign aAlignment,TChar aFill) |
|
1335 { |
|
1336 TInt width = (aWidth == KDefaultJustifyWidth ? aDes.Length() : aWidth); |
|
1337 ReserveL(width); |
|
1338 RBuf8::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 TDes8::Format() |
|
1380 */ |
|
1381 EXPORT_C void LString8::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 LString8::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 LString8::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 LString8::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 LString8::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 TDes8::Num() |
|
1590 @see TDes8::NumUC() |
|
1591 */ |
|
1592 EXPORT_C void LString8::FormatL(TRefByValue<const TDesC8> 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 TDes8::Format() |
|
1622 @see VA_LIST |
|
1623 */ |
|
1624 EXPORT_C void LString8::FormatListL(const TDesC8& 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 8-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 LString8::AppendJustifyL(const TDesC8& Des,TInt aWidth,TAlign aAlignment,TChar aFill) |
|
1669 { |
|
1670 |
|
1671 TInt width = (aWidth == KDefaultJustifyWidth ? Des.Length() : aWidth); |
|
1672 ReserveFreeCapacityGrowExponentialL(width); |
|
1673 RBuf8::AppendJustify(Des, aWidth, aAlignment, aFill); |
|
1674 |
|
1675 } |
|
1676 |
|
1677 /** |
|
1678 Appends data onto the end of this descriptor's data and justifies it. |
|
1679 |
|
1680 The source of the appended data is an existing descriptor. |
|
1681 |
|
1682 The target area is considered to be an area of specified width, immediately |
|
1683 following this descriptor's existing data. Source data is copied into, and |
|
1684 aligned within this target area according to the specified alignment instruction. |
|
1685 |
|
1686 If the length of the target area is larger than the length of the source, |
|
1687 then spare space within the target area is padded with the fill character. |
|
1688 |
|
1689 This leaving variant of the standard, non-leaving descriptor method |
|
1690 differs in that this operation may cause the string descriptor's heap |
|
1691 buffer to be reallocated in order to accommodate the new data. As a |
|
1692 result, MaxLength() and Ptr() may return different values afterwards, |
|
1693 and any existing raw pointers to into the descriptor data may be |
|
1694 invalidated. |
|
1695 |
|
1696 @param aDes An 8-bit non-modifiable descriptor containing the source data. |
|
1697 |
|
1698 @param aLength The length of data to be copied from the source descriptor. |
|
1699 If this is greater than the width of the target area, then |
|
1700 the length of data copied is limited to the width. |
|
1701 The length of data to be copied must not be greater than |
|
1702 the length of the source descriptor. Note that this |
|
1703 condition is not automatically tested. |
|
1704 |
|
1705 @param aWidth The width of the target area. If this has the specific negative |
|
1706 value KDefaultJustifyWidth, then the width is |
|
1707 re-set to the length of the data source. |
|
1708 |
|
1709 @param aAlignment The alignment of the data within the target area. |
|
1710 |
|
1711 @param aFill The fill character used to pad the target area. |
|
1712 |
|
1713 @leave KErrNoMemory if the underlying buffer needs to be |
|
1714 grown and there are insufficient resources to do so |
|
1715 |
|
1716 @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. |
|
1717 */ |
|
1718 EXPORT_C void LString8::AppendJustifyL(const TDesC8& Des,TInt aLength,TInt aWidth,TAlign aAlignment,TChar aFill) |
|
1719 { |
|
1720 |
|
1721 TInt width = (aWidth == KDefaultJustifyWidth ? aLength : aWidth); |
|
1722 ReserveFreeCapacityGrowExponentialL(width); |
|
1723 |
|
1724 RBuf8::AppendJustify(Des, aLength, aWidth, aAlignment, aFill); |
|
1725 } |
|
1726 |
|
1727 /** |
|
1728 Appends a zero terminated string onto the end of this descriptor's data and |
|
1729 justifies it. |
|
1730 |
|
1731 The zero terminator is not copied. |
|
1732 |
|
1733 The target area is considered to be an area of specified width, immediately |
|
1734 following this descriptor's existing data. Source data is copied into, and |
|
1735 aligned within, this target area according to the specified alignment instruction. |
|
1736 |
|
1737 If the length of the target area is larger than the length of the source, |
|
1738 then spare space within the target area is padded with the fill character. |
|
1739 |
|
1740 This leaving variant of the standard, non-leaving descriptor method |
|
1741 differs in that this operation may cause the string descriptor's heap |
|
1742 buffer to be reallocated in order to accommodate the new data. As a |
|
1743 result, MaxLength() and Ptr() may return different values afterwards, |
|
1744 and any existing raw pointers to into the descriptor data may be |
|
1745 invalidated. |
|
1746 |
|
1747 @param aZeroTerminatedString A pointer to a zero terminated string The length of the data |
|
1748 to be copied is the smaller of: the length of the string (excluding the zero |
|
1749 terminator), the width of the target area (only if this is not the explicit |
|
1750 negative value KDefaultJustifyWidth). |
|
1751 |
|
1752 @param aWidth The width of the target area. If this has the specific negative |
|
1753 value KDefaultJustifyWidth, then the width is re-set to the length of the |
|
1754 zero terminated string (excluding the zero terminator). |
|
1755 |
|
1756 @param aAlignment The alignment of the data within the target area. |
|
1757 |
|
1758 @param aFill The fill character used to pad the target area. |
|
1759 |
|
1760 @leave KErrNoMemory if the underlying buffer needs to be |
|
1761 grown and there are insufficient resources to do so |
|
1762 |
|
1763 @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. |
|
1764 */ |
|
1765 EXPORT_C void LString8::AppendJustifyL(const TUint8* aZeroTerminatedString,TInt aWidth,TAlign aAlignment,TChar aFill) |
|
1766 { |
|
1767 |
|
1768 TInt width = (aWidth == KDefaultJustifyWidth ? User::StringLength(aZeroTerminatedString) : aWidth); |
|
1769 ReserveFreeCapacityGrowExponentialL(width); |
|
1770 |
|
1771 RBuf8::AppendJustify(aZeroTerminatedString, aWidth, aAlignment, aFill); |
|
1772 |
|
1773 } |
|
1774 |
|
1775 /** |
|
1776 Appends data onto the end of this descriptor's data and justifies it. |
|
1777 |
|
1778 The source of the appended data is a memory location. |
|
1779 |
|
1780 The target area is considered to be an area of specified width, immediately |
|
1781 following this descriptor's existing data. Source data is copied into, and |
|
1782 aligned within, this target area according to the specified alignment instruction. |
|
1783 |
|
1784 If the length of the target area is larger than the length of the source, |
|
1785 then spare space within the target area is padded with the fill character. |
|
1786 |
|
1787 This leaving variant of the standard, non-leaving descriptor method |
|
1788 differs in that this operation may cause the string descriptor's heap |
|
1789 buffer to be reallocated in order to accommodate the new data. As a |
|
1790 result, MaxLength() and Ptr() may return different values afterwards, |
|
1791 and any existing raw pointers to into the descriptor data may be |
|
1792 invalidated. |
|
1793 |
|
1794 @param aString A pointer to a source memory location. |
|
1795 |
|
1796 @param aLength The length of data to be copied. If this is greater than the |
|
1797 width of the target area, then the length of data copied is |
|
1798 limited to the width. |
|
1799 |
|
1800 @param aWidth The width of the target area. If this has the specific negative |
|
1801 value KDefaultJustifyWidth, then the width is |
|
1802 re-set to the length of the data source. |
|
1803 |
|
1804 @param aAlignment The alignment of the data within the target area. |
|
1805 |
|
1806 @param aFill The fill character used to pad the target area. |
|
1807 |
|
1808 @leave KErrNoMemory if the underlying buffer needs to be |
|
1809 grown and there are insufficient resources to do so |
|
1810 |
|
1811 @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. |
|
1812 |
|
1813 @panic USER 17 if aLength is negative. |
|
1814 */ |
|
1815 EXPORT_C void LString8::AppendJustifyL(const TUint8* aString,TInt aLength,TInt aWidth,TAlign aAlignment,TChar aFill) |
|
1816 { |
|
1817 |
|
1818 TInt width = (aWidth == KDefaultJustifyWidth ? aLength : aWidth); |
|
1819 ReserveFreeCapacityGrowExponentialL(width); |
|
1820 |
|
1821 RBuf8::AppendJustify(aString, aLength, aWidth, aAlignment, aFill); |
|
1822 } |
|
1823 |
|
1824 /** |
|
1825 Converts the specified unsigned integer into a fixed width character |
|
1826 representation based on the specified number system and appends the conversion |
|
1827 onto the end of this descriptor's data. |
|
1828 |
|
1829 The length of this descriptor is incremented to reflect the new content. |
|
1830 |
|
1831 The function generates the exact number of specified characters, either |
|
1832 padding to the left with character zeroes or discarding low order characters |
|
1833 as necessary. |
|
1834 |
|
1835 When a hexadecimal conversion is specified, hexadecimal characters are in |
|
1836 upper case. |
|
1837 |
|
1838 This leaving variant of the standard, non-leaving descriptor method |
|
1839 differs in that this operation may cause the string descriptor's heap |
|
1840 buffer to be reallocated in order to accommodate the new data. As a |
|
1841 result, MaxLength() and Ptr() may return different values afterwards, |
|
1842 and any existing raw pointers to into the descriptor data may be |
|
1843 invalidated. |
|
1844 |
|
1845 @param aVal The unsigned integer value. |
|
1846 @param aRadix The number system representation for the unsigned integer. |
|
1847 @param aWidth The number of characters: to be used to contain the conversion, |
|
1848 to be appended to this descriptor. |
|
1849 |
|
1850 @leave KErrNoMemory if the underlying buffer needs to be |
|
1851 grown and there are insufficient resources to do so |
|
1852 |
|
1853 */ |
|
1854 EXPORT_C void LString8::AppendNumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth) |
|
1855 { |
|
1856 ReserveFreeCapacityGrowExponentialL(aWidth); |
|
1857 RBuf8::AppendNumFixedWidthUC(aVal, aRadix, aWidth); |
|
1858 } |
|
1859 |
|
1860 /** |
|
1861 Converts the specified 64 bit integer into a character representation |
|
1862 based on the specified number system and appends the conversion onto the end |
|
1863 of this descriptor's data. |
|
1864 |
|
1865 The length of this descriptor is incremented to reflect the new content. |
|
1866 |
|
1867 When a hexadecimal conversion is specified, hexadecimal characters are in |
|
1868 upper case. |
|
1869 |
|
1870 This leaving variant of the standard, non-leaving descriptor method |
|
1871 differs in that this operation may cause the string descriptor's heap |
|
1872 buffer to be reallocated in order to accommodate the new data. As a |
|
1873 result, MaxLength() and Ptr() may return different values afterwards, |
|
1874 and any existing raw pointers to into the descriptor data may be |
|
1875 invalidated. |
|
1876 |
|
1877 @param aVal The 64 bit integer value. This is always treated as an unsigned |
|
1878 value. |
|
1879 @param aRadix The number system representation for the 64 bit integer. If no |
|
1880 explicit value is specified, then EDecimal is the default. |
|
1881 |
|
1882 @leave KErrNoMemory if the underlying buffer needs to be |
|
1883 grown and there are insufficient resources to do so |
|
1884 */ |
|
1885 EXPORT_C void LString8::AppendNumUCL(TUint64 aVal, TRadix aRadix) |
|
1886 { |
|
1887 ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize); |
|
1888 RBuf8::AppendNumUC(aVal, aRadix); |
|
1889 } |
|
1890 |
|
1891 /** |
|
1892 Converts the specified floating point number into a character representation |
|
1893 and appends the conversion onto the end of this descriptor's data. |
|
1894 |
|
1895 The length of this descriptor is incremented to reflect the new content. |
|
1896 |
|
1897 The character representation of the real number is dictated by the specified |
|
1898 format. |
|
1899 |
|
1900 This leaving variant of the standard, non-leaving descriptor method |
|
1901 differs in that this operation may cause the string descriptor's heap |
|
1902 buffer to be reallocated in order to accommodate the new data. As a |
|
1903 result, MaxLength() and Ptr() may return different values afterwards, |
|
1904 and any existing raw pointers to into the descriptor data may be |
|
1905 invalidated. |
|
1906 |
|
1907 @param aVal The floating point number to be converted. |
|
1908 @param aFormat The format of the conversion. |
|
1909 |
|
1910 @return If the conversion is successful, the length of this descriptor. If |
|
1911 the conversion fails, a negative value indicating the cause of failure. |
|
1912 In addition, extra information on the cause of the failure may be |
|
1913 appended onto this descriptor. The possible values and their meaning |
|
1914 are: |
|
1915 |
|
1916 1.KErrArgument - the supplied floating point number is not a valid |
|
1917 number. The three characters NaN are appended to this descriptor. |
|
1918 |
|
1919 2.KErrOverflow - the number is too large to represent. |
|
1920 2.1 For positive overflow, the three characters Inf are appended |
|
1921 to this descriptor. |
|
1922 2.2 For negative overflow, the four characters -Inf are appended |
|
1923 to this descriptor. |
|
1924 |
|
1925 3.KErrUnderflow - the number is too small to represent. |
|
1926 3.1 For positive underflow, the three characters Inf are appended |
|
1927 to this descriptor. |
|
1928 3.2 For negative underflow, the four characters -Inf are appended |
|
1929 to this descriptor. |
|
1930 |
|
1931 4.KErrGeneral - the conversion cannot be completed. There are a |
|
1932 number of possible reasons for this, but the most common is: |
|
1933 4.1 The character representation format (i.e. the format type), as |
|
1934 defined in the TRealFormat object is not recognised. |
|
1935 |
|
1936 @leave KErrNoMemory if the underlying buffer needs to be |
|
1937 grown and there are insufficient resources to do so |
|
1938 */ |
|
1939 EXPORT_C TInt LString8::AppendNumL(TReal aVal,const TRealFormat& aFormat) |
|
1940 { |
|
1941 ReserveFreeCapacityGrowExponentialL(aFormat.iWidth + 1 + KDefaultExpandSize); |
|
1942 return RBuf8::AppendNum(aVal, aFormat); |
|
1943 } |
|
1944 |
|
1945 /** |
|
1946 Converts the 64-bit signed integer into a decimal character representation |
|
1947 and appends the conversion onto the end of this descriptor's data. |
|
1948 |
|
1949 The length of this descriptor is incremented to reflect the new content. |
|
1950 |
|
1951 If the integer is negative, the character representation is prefixed by a |
|
1952 minus sign. |
|
1953 |
|
1954 This leaving variant of the standard, non-leaving descriptor method |
|
1955 differs in that this operation may cause the string descriptor's heap |
|
1956 buffer to be reallocated in order to accommodate the new data. As a |
|
1957 result, MaxLength() and Ptr() may return different values afterwards, |
|
1958 and any existing raw pointers to into the descriptor data may be |
|
1959 invalidated. |
|
1960 |
|
1961 @param aVal The 64-bit signed integer value. |
|
1962 |
|
1963 @leave KErrNoMemory if the underlying buffer needs to be |
|
1964 grown and there are insufficient resources to do so |
|
1965 */ |
|
1966 EXPORT_C void LString8::AppendNumL(TInt64 aVal) |
|
1967 { |
|
1968 ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize); |
|
1969 RBuf8::AppendNum(aVal); |
|
1970 } |
|
1971 |
|
1972 /** |
|
1973 Converts the specified 64 bit integer into a character representation |
|
1974 based on the specified number system and appends the conversion onto the end |
|
1975 of this descriptor's data. |
|
1976 |
|
1977 The length of this descriptor is incremented to reflect the new content. |
|
1978 |
|
1979 When a hexadecimal conversion is specified, hexadecimal characters are in |
|
1980 lower case. |
|
1981 |
|
1982 This leaving variant of the standard, non-leaving descriptor method |
|
1983 differs in that this operation may cause the string descriptor's heap |
|
1984 buffer to be reallocated in order to accommodate the new data. As a |
|
1985 result, MaxLength() and Ptr() may return different values afterwards, |
|
1986 and any existing raw pointers to into the descriptor data may be |
|
1987 invalidated. |
|
1988 |
|
1989 @param aVal The 64 bit integer value. This is always treated as an unsigned |
|
1990 value. |
|
1991 @param aRadix The number system representation for the 64 bit integer. |
|
1992 |
|
1993 @leave KErrNoMemory if the underlying buffer needs to be |
|
1994 grown and there are insufficient resources to do so |
|
1995 */ |
|
1996 EXPORT_C void LString8::AppendNumL(TUint64 aVal, TRadix aRadix) |
|
1997 { |
|
1998 ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize); |
|
1999 RBuf8::AppendNum(aVal, aRadix); |
|
2000 } |
|
2001 |
|
2002 /** |
|
2003 Formats and appends text onto the end of this descriptor's data. |
|
2004 |
|
2005 The length of this descriptor is incremented to reflect the new content. |
|
2006 |
|
2007 The function takes a format string and a variable number of arguments. |
|
2008 The format string contains literal text, embedded with directives, |
|
2009 for converting the trailing list of arguments into text. |
|
2010 |
|
2011 The embedded directives are character sequences prefixed with the '%' character. |
|
2012 The literal text is simply copied into this descriptor unaltered while |
|
2013 the '%' directives are used to convert successive arguments from the |
|
2014 trailing list. See the description of the Format() function. |
|
2015 |
|
2016 Literal text is appended on a character by character basis, and the |
|
2017 underlying buffer is grown as necessary to accommodate it. |
|
2018 |
|
2019 Text converted from a trailing argument is appended as a complete |
|
2020 string, and the underlying buffer is grown as necessary to accommodate |
|
2021 it. |
|
2022 |
|
2023 This leaving variant of the standard, non-leaving descriptor method |
|
2024 differs in that this operation may cause the string descriptor's heap |
|
2025 buffer to be reallocated in order to accommodate the new data. As a |
|
2026 result, MaxLength() and Ptr() may return different values afterwards, |
|
2027 and any existing raw pointers to into the descriptor data may be |
|
2028 invalidated. |
|
2029 |
|
2030 @param aFmt The 8-bit non-modifiable descriptor containing the |
|
2031 format string. The TRefByValue class provides a |
|
2032 constructor which takes a TDesC8 type. |
|
2033 |
|
2034 @param ... A variable number of arguments to be converted to text |
|
2035 as dictated by the format string. |
|
2036 |
|
2037 @leave KErrNoMemory if the underlying buffer needs to be |
|
2038 grown and there are insufficient resources to do so |
|
2039 |
|
2040 @panic USER 12 if the format string has incorrect syntax. |
|
2041 |
|
2042 @see TDes8::Format() |
|
2043 @see TDes8Overflow::Overflow() |
|
2044 */ |
|
2045 EXPORT_C void LString8::AppendFormatL(TRefByValue<const TDesC8> aFmt,...) |
|
2046 { |
|
2047 VA_LIST list; |
|
2048 VA_START(list,aFmt); |
|
2049 AppendFormatListL(aFmt,list); |
|
2050 } |
|
2051 |
|
2052 class TRetryOverflow8 : public TDes8Overflow |
|
2053 { |
|
2054 public: |
|
2055 TRetryOverflow8() : iOverflow(EFalse) |
|
2056 { |
|
2057 } |
|
2058 |
|
2059 virtual void Overflow(TDes8& /*aDes*/) |
|
2060 { |
|
2061 iOverflow = ETrue; |
|
2062 } |
|
2063 |
|
2064 TBool iOverflow; |
|
2065 }; |
|
2066 |
|
2067 /** |
|
2068 Formats and appends text onto the end of this descriptor's data. |
|
2069 |
|
2070 The length of this descriptor is incremented to reflect the new content. |
|
2071 |
|
2072 The behaviour of this function is the same as |
|
2073 AppendFormatL(TRefByValue<const TDesC8> aFmt,TDes8Overflow *aOverflowHandler,...). |
|
2074 In practice, it is better and easier to use AppendFormat(), passing a variable number of |
|
2075 arguments as required by the format string. |
|
2076 |
|
2077 This leaving variant of the standard, non-leaving descriptor method |
|
2078 differs in that this operation may cause the string descriptor's heap |
|
2079 buffer to be reallocated in order to accommodate the new data. As a |
|
2080 result, MaxLength() and Ptr() may return different values afterwards, |
|
2081 and any existing raw pointers to into the descriptor data may be |
|
2082 invalidated. |
|
2083 |
|
2084 @param aFmt The descriptor containing the format string. |
|
2085 @param aList A pointer to an argument list. |
|
2086 |
|
2087 @leave KErrNoMemory if the underlying buffer needs to be |
|
2088 grown and there are insufficient resources to do so |
|
2089 |
|
2090 @see TDes8::AppendFormat |
|
2091 @see VA_LIST |
|
2092 */ |
|
2093 EXPORT_C void LString8::AppendFormatListL(const TDesC8& aFmt,VA_LIST aList) |
|
2094 { |
|
2095 ReserveFreeCapacityGrowExponentialL(aFmt.Length() + KDefaultExpandSize); // We use aFmt as a hint |
|
2096 for (;;) |
|
2097 { |
|
2098 TInt before = Length(); |
|
2099 TRetryOverflow8 overflow; |
|
2100 RBuf8::AppendFormatList(aFmt, aList, &overflow); |
|
2101 if (overflow.iOverflow) |
|
2102 { |
|
2103 SetLengthL(before); // Can't leave |
|
2104 ReserveCapacityGrowExponentialL(); |
|
2105 } |
|
2106 else |
|
2107 { |
|
2108 break; |
|
2109 } |
|
2110 } |
|
2111 } |
|
2112 |
|
2113 |
|
2114 /** |
|
2115 Unlinks and transfers ownership of the specified 8-bit resizable descriptor's |
|
2116 buffer to this object. The source descriptor is detached from the buffer. |
|
2117 |
|
2118 @param aString The source 8-bit resizable buffer. The ownership of this |
|
2119 object's buffer is to be transferred. |
|
2120 |
|
2121 */ |
|
2122 EXPORT_C void LString8::Assign(const LString8& aString) |
|
2123 { |
|
2124 // free any previously owned resource |
|
2125 Reset(); |
|
2126 |
|
2127 RBuf8::Assign(aString); |
|
2128 // unlink buffer from original descriptor |
|
2129 new (const_cast<LString8*>(&aString)) LString8(); |
|
2130 } |
|
2131 |
|
2132 |
|
2133 /** |
|
2134 Transfers ownership of the specified 8-bit resizable descriptor's |
|
2135 buffer to this object. The source descriptor is detached from the buffer. |
|
2136 |
|
2137 @param aRBuf The source 8-bit resizable buffer. The ownership of this |
|
2138 object's buffer is to be transferred. |
|
2139 |
|
2140 @see RBuf8::Assign() |
|
2141 */ |
|
2142 |
|
2143 EXPORT_C void LString8::Assign(const RBuf8& aRBuf) |
|
2144 { |
|
2145 // free any previously owned resource |
|
2146 Reset(); |
|
2147 |
|
2148 RBuf8::Assign(aRBuf); |
|
2149 |
|
2150 // reset the RBuf; |
|
2151 new (const_cast<RBuf8*>(&aRBuf)) RBuf8(); |
|
2152 } |
|
2153 |
|
2154 |
|
2155 /** |
|
2156 Transfers ownership of the specified 8-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 RBuf8::Assign() |
|
2162 */ |
|
2163 EXPORT_C void LString8::Assign(HBufC8* aHBuf) |
|
2164 { |
|
2165 // free any previously owned resource |
|
2166 Reset(); |
|
2167 |
|
2168 RBuf8::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 8-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 RBuf8::Assign() |
|
2186 */ |
|
2187 EXPORT_C void LString8::Assign(TUint8 *aHeapCell, TInt aMaxLength) |
|
2188 { |
|
2189 // free any previously owned resource |
|
2190 Reset(); |
|
2191 |
|
2192 RBuf8::Assign(aHeapCell, aMaxLength); |
|
2193 } |
|
2194 |
|
2195 |
|
2196 /** |
|
2197 Transfers ownership of the specified 16-bit resizable descriptor's this object. |
|
2198 |
|
2199 @param aHeapCell The allocated memory to be assigned to this object. |
|
2200 |
|
2201 @param aLength The length of the descriptor. |
|
2202 |
|
2203 @param aMaxLength The maximum length of the descriptor. |
|
2204 |
|
2205 @panic USER 8 If the specified maximum length is greater then the size of the |
|
2206 allocated heap cell, or the specified length is greater then |
|
2207 the specified maximum length, or the specified maximum length |
|
2208 is NOT zero when the pointer to the heap cell is NULL. |
|
2209 |
|
2210 @see RBuf8::Assign() |
|
2211 */ |
|
2212 EXPORT_C void LString8::Assign(TUint8* aHeapCell,TInt aLength,TInt aMaxLength) |
|
2213 { |
|
2214 // free any previously owned resource |
|
2215 Reset(); |
|
2216 |
|
2217 RBuf8::Assign(aHeapCell, aLength, aMaxLength); |
|
2218 } |
|
2219 |
|
2220 /** |
|
2221 Creates an 8-bit resizable buffer descriptor that has been initialised with |
|
2222 data from the specified read stream; leaves on failure. |
|
2223 |
|
2224 Data is assigned to the new descriptor from the specified stream. |
|
2225 This variant assumes that the stream contains the length of the data followed |
|
2226 by the data itself. |
|
2227 |
|
2228 The function is implemented by calling the HBufC8::NewL(RReadStream&,TInt) |
|
2229 variant and then assigning the resulting heap descriptor using |
|
2230 the RBuf8::Assign(HBufC8*) variant. The comments that describe |
|
2231 the HBufC8::NewL() variant also apply to this RBuf8::CreateL() function. |
|
2232 |
|
2233 The function may leave with one of the system-wide error codes, specifically |
|
2234 KErrOverflow, if the length of the data as read from the stream is greater than |
|
2235 the upper limit as specified by the aMaxLength parameter. |
|
2236 |
|
2237 @param aStream The stream from which the data length and the data to be |
|
2238 assigned to the new descriptor, are taken. |
|
2239 @param aMaxLength The upper limit on the length of data that the descriptor is |
|
2240 to represent. The value of this parameter must be non-negative |
|
2241 otherwise the underlying function will panic. |
|
2242 */ |
|
2243 EXPORT_C void LString8::CreateL(RReadStream &aStream,TInt aMaxLength) |
|
2244 { |
|
2245 Reset(); |
|
2246 Assign(HBufC8::NewL(aStream,aMaxLength)); |
|
2247 } |
|
2248 |
|
2249 /** |
|
2250 Appends data onto the end of this descriptor's data. |
|
2251 |
|
2252 The length of this descriptor is incremented to reflect the new content. |
|
2253 |
|
2254 This leaving variant of the standard, non-leaving descriptor method |
|
2255 differs in that this operation may cause the string descriptor's heap |
|
2256 buffer to be reallocated in order to accommodate the new data. As a |
|
2257 result, MaxLength() and Ptr() may return different values afterwards, |
|
2258 and any existing raw pointers to into the descriptor data may be |
|
2259 invalidated. |
|
2260 |
|
2261 @param aZeroTerminatedString A pointer to a zero terminated string . |
|
2262 @leave KErrNoMemory if the underlying buffer needs to be |
|
2263 grown and there are insufficient resources to do so |
|
2264 |
|
2265 @see LString8::AppendL |
|
2266 */ |
|
2267 EXPORT_C LString8& LString8::operator+=(const TUint8* aZeroTerminatedString) |
|
2268 { |
|
2269 AppendL(aZeroTerminatedString,User::StringLength(aZeroTerminatedString)); |
|
2270 return *this; |
|
2271 } |
|
2272 /** |
|
2273 Appends data onto the end of this descriptor's data. |
|
2274 |
|
2275 The length of this descriptor is incremented to reflect the new content. |
|
2276 |
|
2277 This leaving variant of the standard, non-leaving descriptor method |
|
2278 differs in that this operation may cause the string descriptor's heap |
|
2279 buffer to be reallocated in order to accommodate the new data. As a |
|
2280 result, MaxLength() and Ptr() may return different values afterwards, |
|
2281 and any existing raw pointers to into the descriptor data may be |
|
2282 invalidated. |
|
2283 |
|
2284 @param aZeroTerminatedString A pointer to the data to be copied. |
|
2285 |
|
2286 @leave KErrNoMemory if the underlying buffer needs to be |
|
2287 grown and there are insufficient resources to do so |
|
2288 |
|
2289 @panic USER 17 if aLength is negative. |
|
2290 */ |
|
2291 EXPORT_C void LString8::AppendL(const TUint8* aZeroTerminatedString) |
|
2292 { |
|
2293 AppendL(aZeroTerminatedString,User::StringLength(aZeroTerminatedString)); |
|
2294 } |
|
2295 /** |
|
2296 Constructor to create a 8-bit resizable string descriptor containing |
|
2297 a copy of the specified (source) zero-terminated character string data, or leave |
|
2298 on failure. |
|
2299 |
|
2300 The constructor allocates sufficient memory so that this string |
|
2301 descriptor's maximum length is the same as the length of the source |
|
2302 string. Both the current length and the maximum length of this string |
|
2303 descriptor are set to the length of the source string. |
|
2304 |
|
2305 The data contained in the source string is copied into this string |
|
2306 descriptor. The zero terminator is not copied. |
|
2307 |
|
2308 @param aCharStr A pointer to a zero-terminated wide character string |
|
2309 |
|
2310 @leave KErrNoMemory If there is insufficient memory. |
|
2311 |
|
2312 @see LString8::CopyL |
|
2313 */ |
|
2314 EXPORT_C LString8::LString8(const char* aCharStr) |
|
2315 : iReserved(0) |
|
2316 { |
|
2317 CopyL(reinterpret_cast<const TUint8*>(aCharStr)); |
|
2318 } |
|
2319 |
|
2320 /** |
|
2321 Copies data into this 8-bit string descriptor, replacing any existing |
|
2322 data, and expanding its heap buffer to accommodate if necessary. |
|
2323 |
|
2324 The length of this descriptor is set to reflect the new data. |
|
2325 |
|
2326 This operation may cause the target string descriptor's heap buffer to |
|
2327 be reallocated in order to accommodate the new data. As a result, |
|
2328 MaxLength() and Ptr() may return different values afterwards, and any |
|
2329 existing raw pointers to into the descriptor data may be invalidated. |
|
2330 |
|
2331 Note that the automatic resizing performed is a change to the |
|
2332 functionality of this operation compared to other descriptor |
|
2333 classes. This change is only active on objects directly declared |
|
2334 LString8; when LString8 instances are instead manipulated via |
|
2335 references to TDes8 or TDesC8, the standard (non-resizing, panicing) |
|
2336 variant is invoked. |
|
2337 |
|
2338 @param aCharStr A pointer to a character zero-terminated string |
|
2339 |
|
2340 @return A reference to this 8-bit string descriptor. |
|
2341 |
|
2342 @leave KErrNoMemory If the heap buffer of the string descriptor being |
|
2343 assigned to needs to be expanded, but there is |
|
2344 insufficient memory to do so |
|
2345 |
|
2346 @see LString8::CopyL |
|
2347 */ |
|
2348 EXPORT_C LString8& LString8::operator=(const char* aCharStr) |
|
2349 { |
|
2350 CopyL(reinterpret_cast<const TUint8*>(aCharStr)); |
|
2351 return *this; |
|
2352 } |
|
2353 |
|
2354 /** |
|
2355 Appends data onto the end of this descriptor's data. |
|
2356 |
|
2357 The length of this descriptor is incremented to reflect the new content. |
|
2358 |
|
2359 This leaving variant of the standard, non-leaving descriptor method |
|
2360 differs in that this operation may cause the string descriptor's heap |
|
2361 buffer to be reallocated in order to accommodate the new data. As a |
|
2362 result, MaxLength() and Ptr() may return different values afterwards, |
|
2363 and any existing raw pointers to into the descriptor data may be |
|
2364 invalidated. |
|
2365 |
|
2366 @param aCharStr A pointer to a character zero terminated string . |
|
2367 @leave KErrNoMemory if the underlying buffer needs to be |
|
2368 grown and there are insufficient resources to do so |
|
2369 |
|
2370 @see LString8::AppendL |
|
2371 */ |
|
2372 EXPORT_C LString8& LString8::operator+=(const char* aCharStr) |
|
2373 { |
|
2374 AppendL(reinterpret_cast<const TUint8*>(aCharStr),User::StringLength(reinterpret_cast<const TUint8*>(aCharStr))); |
|
2375 return *this; |
|
2376 } |
|
2377 |
|
2378 /** |
|
2379 Copies data into this 8-bit string descriptor, replacing any existing |
|
2380 data, and expanding its heap buffer to accommodate if necessary. |
|
2381 |
|
2382 The length of this descriptor is set according to the new |
|
2383 parameter. |
|
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 aCharStr A pointer to a 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 TDes8::Copy |
|
2402 */ |
|
2403 EXPORT_C void LString8::CopyL(const char* aCharStr) |
|
2404 { |
|
2405 CopyL(reinterpret_cast<const TUint8*>(aCharStr)); |
|
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 aCharStr 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 LString8::AppendJustifyL(const char* aCharStr,TInt aWidth,TAlign anAlignment,TChar aFill) |
|
2449 { |
|
2450 AppendJustifyL(reinterpret_cast<const TUint8*>( aCharStr),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 aCharStr 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 LString8::AppendL(const char* aCharStr,TInt aLength) |
|
2474 { |
|
2475 AppendL(reinterpret_cast<const TUint8*>(aCharStr),aLength); |
|
2476 } |
|
2477 |
|
2478 /** |
|
2479 Appends data onto the end of this descriptor's data. |
|
2480 |
|
2481 The length of this descriptor is incremented to reflect the new content. |
|
2482 |
|
2483 This leaving variant of the standard, non-leaving descriptor method |
|
2484 differs in that this operation may cause the string descriptor's heap |
|
2485 buffer to be reallocated in order to accommodate the new data. As a |
|
2486 result, MaxLength() and Ptr() may return different values afterwards, |
|
2487 and any existing raw pointers to into the descriptor data may be |
|
2488 invalidated. |
|
2489 |
|
2490 @param aCharStr A pointer to the data to be copied. |
|
2491 |
|
2492 @leave KErrNoMemory if the underlying buffer needs to be |
|
2493 grown and there are insufficient resources to do so |
|
2494 |
|
2495 @panic USER 17 if aLength is negative. |
|
2496 */ |
|
2497 EXPORT_C void LString8::AppendL(const char* aCharStr) |
|
2498 { |
|
2499 AppendL(reinterpret_cast<const TUint8*>(aCharStr)); |
|
2500 } |
|
2501 |
|
2502 /** |
|
2503 Determines whether this Descriptor's data is equal to the specified |
|
2504 string's data. |
|
2505 |
|
2506 The comparison is implemented internally using the TDesC8::Compare() function. |
|
2507 |
|
2508 @param aCharStr The 8-bit character string whose data is to be compared |
|
2509 with this Descriptor's data. |
|
2510 |
|
2511 @return True if equal, false otherwise. |
|
2512 |
|
2513 @see TDesC8::Compare |
|
2514 */ |
|
2515 EXPORT_C TBool LString8::operator==( const char* aCharStr) const |
|
2516 { |
|
2517 return LString8::operator==(reinterpret_cast<const TUint8*>(aCharStr)); |
|
2518 } |
|
2519 |
|
2520 /** |
|
2521 Determines whether this Descriptor's data is equal to the specified |
|
2522 string's data. |
|
2523 |
|
2524 The comparison is implemented internally using the TDesC8::Compare() function. |
|
2525 |
|
2526 @param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data |
|
2527 is to be compared with this Descriptor's data. |
|
2528 |
|
2529 @return True if equal, false otherwise. |
|
2530 |
|
2531 @see TDesC8::Compare |
|
2532 */ |
|
2533 EXPORT_C TBool LString8::operator==( const TUint8* aZeroTerminatedString) const |
|
2534 { |
|
2535 return RBuf8::operator==(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
2536 } |
|
2537 |
|
2538 /** |
|
2539 Determines whether this descriptor's data is less than the specified |
|
2540 strings's data. |
|
2541 |
|
2542 The comparison is implemented internally using the TDesC8::Compare() function. |
|
2543 |
|
2544 @param aCharStr The 8-bit character string whose data is to be compared |
|
2545 with this Descriptor's data. |
|
2546 |
|
2547 @return True if this descriptor's data is less than that of the specified string's data |
|
2548 |
|
2549 @see TDesC8::Compare |
|
2550 */ |
|
2551 EXPORT_C TBool LString8::operator<( const char* aCharStr) const |
|
2552 { |
|
2553 return LString8::operator<(reinterpret_cast<const TUint8*>(aCharStr)); |
|
2554 } |
|
2555 |
|
2556 /** |
|
2557 Determines whether this descriptor's data is less than the specified |
|
2558 strings's data. |
|
2559 |
|
2560 The comparison is implemented internally using the TDesC8::Compare() function. |
|
2561 |
|
2562 @param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data |
|
2563 is to be compared with this Descriptor's data. |
|
2564 |
|
2565 @return True if this descriptor's data is less than that of the specified string's data |
|
2566 |
|
2567 @see TDesC8::Compare |
|
2568 */ |
|
2569 EXPORT_C TBool LString8::operator<(const TUint8* aZeroTerminatedString) const |
|
2570 { |
|
2571 return RBuf8::operator<(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
2572 } |
|
2573 |
|
2574 /** |
|
2575 Determines whether this descriptor's data is less than the specified |
|
2576 strings's data. |
|
2577 |
|
2578 The comparison is implemented internally using the TDesC8::Compare() function. |
|
2579 |
|
2580 @param aCharStr The 8-bit character string whose data is to be compared |
|
2581 with this Descriptor's data. |
|
2582 |
|
2583 @return True if this descriptor's data is less than that of the specified string's data |
|
2584 |
|
2585 @see TDesC8::Compare |
|
2586 */ |
|
2587 EXPORT_C TBool LString8::operator<=( const char* aCharStr) const |
|
2588 { |
|
2589 return LString8::operator<=(reinterpret_cast<const TUint8*>(aCharStr)); |
|
2590 } |
|
2591 |
|
2592 /** |
|
2593 Determines whether this descriptor's data is less than/equal to the specified |
|
2594 strings's data. |
|
2595 |
|
2596 The comparison is implemented internally using the TDesC8::Compare() function. |
|
2597 |
|
2598 @param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data |
|
2599 is to be compared with this Descriptor's data. |
|
2600 |
|
2601 @return True if this descriptor's data is less than/equal to that of the specified string's data |
|
2602 |
|
2603 @see TDesC8::Compare |
|
2604 */ |
|
2605 EXPORT_C TBool LString8::operator<=(const TUint8* aZeroTerminatedString) const |
|
2606 { |
|
2607 return RBuf8::operator<=(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
2608 } |
|
2609 |
|
2610 /** |
|
2611 Determines whether this descriptor's data is greater than the specified |
|
2612 strings's data. |
|
2613 |
|
2614 The comparison is implemented internally using the TDesC8::Compare() function. |
|
2615 |
|
2616 @param aCharStr The 8-bit character string whose data is to be compared |
|
2617 with this Descriptor's data. |
|
2618 |
|
2619 @return True if this descriptor's data is greater than that of the specified string's data |
|
2620 |
|
2621 @see TDesC8::Compare |
|
2622 */ |
|
2623 EXPORT_C TBool LString8::operator>( const char* aCharStr) const |
|
2624 { |
|
2625 return LString8::operator>(reinterpret_cast<const TUint8*>(aCharStr)); |
|
2626 } |
|
2627 |
|
2628 /** |
|
2629 Determines whether this descriptor's data is greater than the specified |
|
2630 strings's data. |
|
2631 |
|
2632 The comparison is implemented internally using the TDesC8::Compare() function. |
|
2633 |
|
2634 @param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data |
|
2635 is to be compared with this Descriptor's data. |
|
2636 |
|
2637 @return True if this descriptor's data is greater than that of the specified string's data |
|
2638 |
|
2639 @see TDesC8::Compare |
|
2640 */ |
|
2641 EXPORT_C TBool LString8::operator>(const TUint8* aZeroTerminatedString) const |
|
2642 { |
|
2643 return RBuf8::operator>(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
2644 } |
|
2645 |
|
2646 /** |
|
2647 Determines whether this descriptor's data is greater than/equal to the specified |
|
2648 strings's data. |
|
2649 |
|
2650 The comparison is implemented internally using the TDesC8::Compare() function. |
|
2651 |
|
2652 @param aCharStr The 8-bit character string whose data is to be compared |
|
2653 with this Descriptor's data. |
|
2654 |
|
2655 @return True if this descriptor's data is greater than/equal to that of the specified string's data |
|
2656 |
|
2657 @see TDesC8::Compare |
|
2658 */ |
|
2659 EXPORT_C TBool LString8::operator>=( const char* aCharStr) const |
|
2660 { |
|
2661 return LString8::operator>=(reinterpret_cast<const TUint8*>(aCharStr)); |
|
2662 } |
|
2663 |
|
2664 /** |
|
2665 Determines whether this descriptor's data is greater than the specified |
|
2666 strings's data. |
|
2667 |
|
2668 The comparison is implemented internally using the TDesC8::Compare() function. |
|
2669 |
|
2670 @param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data |
|
2671 is to be compared with this Descriptor's data. |
|
2672 |
|
2673 @return True if this descriptor's data is greater than that of the specified string's data |
|
2674 |
|
2675 @see TDesC8::Compare |
|
2676 */ |
|
2677 EXPORT_C TBool LString8::operator>=(const TUint8* aZeroTerminatedString) const |
|
2678 { |
|
2679 return RBuf8::operator>=(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
2680 } |
|
2681 |
|
2682 /** |
|
2683 Determines whether this descriptor's data is not equal to the specified |
|
2684 strings's data. |
|
2685 |
|
2686 The comparison is implemented internally using the TDesC8::Compare() function. |
|
2687 |
|
2688 @param aCharStr The 8-bit character string whose data is to be compared |
|
2689 with this Descriptor's data. |
|
2690 |
|
2691 @return True if this descriptor's data is not equal to the specified string's data |
|
2692 |
|
2693 @see TDesC8::Compare |
|
2694 */ |
|
2695 EXPORT_C TBool LString8::operator!=( const char* aCharStr) const |
|
2696 { |
|
2697 return LString8::operator!=(reinterpret_cast<const TUint8*>(aCharStr)); |
|
2698 } |
|
2699 |
|
2700 /** |
|
2701 Determines whether this descriptor's data is not equal to the specified |
|
2702 strings's data. |
|
2703 |
|
2704 The comparison is implemented internally using the TDesC8::Compare() function. |
|
2705 |
|
2706 @param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data |
|
2707 is to be compared with this Descriptor's data. |
|
2708 |
|
2709 @return True if this descriptor's data is not equal to the specified string's data |
|
2710 |
|
2711 @see TDesC8::Compare |
|
2712 */ |
|
2713 EXPORT_C TBool LString8::operator!=(const TUint8* aZeroTerminatedString) const |
|
2714 { |
|
2715 return RBuf8::operator!=(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
2716 } |
|
2717 |
|
2718 /** |
|
2719 Searches this descriptor's data for a match with the match pattern supplied |
|
2720 in the specified string. |
|
2721 |
|
2722 The match pattern can contain the wildcard characters "*" and "?", where "*" |
|
2723 matches zero or more consecutive occurrences of any character and "?" matches |
|
2724 a single occurrence of any character. |
|
2725 |
|
2726 Note that there is no 'escape character', which means that it is not possible |
|
2727 to match either the "*" character itself or the "?" character itself using |
|
2728 this function. |
|
2729 |
|
2730 @param aCharStr The 8-bit character string whose data is to be matched |
|
2731 with this Descriptor's data. |
|
2732 |
|
2733 @return If a match is found, the offset within this descriptor's data where |
|
2734 the match first occurs. KErrNotFound, if there is no match. |
|
2735 */ |
|
2736 EXPORT_C TInt LString8::Match(const char* aCharStr) const |
|
2737 { |
|
2738 return LString8::Match(reinterpret_cast<const TUint8*>(aCharStr)); |
|
2739 } |
|
2740 |
|
2741 /** |
|
2742 Searches this descriptor's data for a match with the match pattern supplied |
|
2743 in the specified string. |
|
2744 |
|
2745 The match pattern can contain the wildcard characters "*" and "?", where "*" |
|
2746 matches zero or more consecutive occurrences of any character and "?" matches |
|
2747 a single occurrence of any character. |
|
2748 |
|
2749 Note that there is no 'escape character', which means that it is not possible |
|
2750 to match either the "*" character itself or the "?" character itself using |
|
2751 this function. |
|
2752 |
|
2753 @param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data |
|
2754 is to be matched with this Descriptor's data. |
|
2755 |
|
2756 @return If a match is found, the offset within this descriptor's data where |
|
2757 the match first occurs. KErrNotFound, if there is no match. |
|
2758 */ |
|
2759 EXPORT_C TInt LString8::Match(const TUint8* aZeroTerminatedString) const |
|
2760 { |
|
2761 return RBuf8::Match(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
2762 } |
|
2763 /** |
|
2764 Searches this descriptor's folded data for a match with the folded match |
|
2765 pattern supplied in the specified string. |
|
2766 |
|
2767 The match pattern can contain the wildcard characters "*" and "?", where "*" |
|
2768 matches zero or more consecutive occurrences of any character and "?" matches |
|
2769 a single occurrence of any character. |
|
2770 |
|
2771 Note that folding is locale-independent behaviour. It is also important to |
|
2772 note that there can be no guarantee that folding is in any way culturally |
|
2773 appropriate, and should not be used for matching strings in natural language; |
|
2774 use MatchC() for this. |
|
2775 |
|
2776 Note that there is no 'escape character', which means that it is not possible |
|
2777 to match either the "*" character itself or the "?" character itself using |
|
2778 this function. |
|
2779 |
|
2780 @param aCharStr The 8-bit character string whose data is to be matched |
|
2781 with this Descriptor's data. |
|
2782 |
|
2783 @return If a match is found, the offset within this descriptor's data where |
|
2784 the match first occurs. KErrNotFound, if there is no match. |
|
2785 |
|
2786 @see TDesC8::MatchC() |
|
2787 */ |
|
2788 EXPORT_C TInt LString8::MatchF(const char* aCharStr) const |
|
2789 { |
|
2790 return LString8::MatchF(reinterpret_cast<const TUint8*>(aCharStr)); |
|
2791 } |
|
2792 /** |
|
2793 Searches this descriptor's folded data for a match with the folded match |
|
2794 pattern supplied in the specified string. |
|
2795 |
|
2796 The match pattern can contain the wildcard characters "*" and "?", where "*" |
|
2797 matches zero or more consecutive occurrences of any character and "?" matches |
|
2798 a single occurrence of any character. |
|
2799 |
|
2800 Note that folding is locale-independent behaviour. It is also important to |
|
2801 note that there can be no guarantee that folding is in any way culturally |
|
2802 appropriate, and should not be used for matching strings in natural language; |
|
2803 use MatchC() for this. |
|
2804 |
|
2805 Note that there is no 'escape character', which means that it is not possible |
|
2806 to match either the "*" character itself or the "?" character itself using |
|
2807 this function. |
|
2808 |
|
2809 @param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data |
|
2810 is to be matched with this Descriptor's data. |
|
2811 |
|
2812 @return If a match is found, the offset within this descriptor's data where |
|
2813 the match first occurs. KErrNotFound, if there is no match. |
|
2814 |
|
2815 @see TDesC8::MatchC() |
|
2816 */ |
|
2817 EXPORT_C TInt LString8::MatchF(const TUint8* aZeroTerminatedString) const |
|
2818 { |
|
2819 return RBuf8::MatchF(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
2820 } |
|
2821 /** |
|
2822 Compares this descriptor's data with the specified string's data. |
|
2823 |
|
2824 The comparison proceeds on a byte for byte basis. The result of the comparison |
|
2825 is based on the difference of the first bytes to disagree. |
|
2826 |
|
2827 @param aCharStr The 8-bit character string whose data is to be compared |
|
2828 with this Descriptor's data. |
|
2829 |
|
2830 @return Positive, if this descriptor is greater than the specified string. |
|
2831 Negative, if this descriptor is less than the specified string. |
|
2832 Zero, if both the descriptor and the string have the same length |
|
2833 and the their contents are the same. |
|
2834 */ |
|
2835 EXPORT_C TInt LString8::Compare(const char* aCharStr) const |
|
2836 { |
|
2837 return LString8::Compare(reinterpret_cast<const TUint8*>(aCharStr)); |
|
2838 } |
|
2839 |
|
2840 /** |
|
2841 Compares this descriptor's data with the specified string's data. |
|
2842 |
|
2843 The comparison proceeds on a byte for byte basis. The result of the comparison |
|
2844 is based on the difference of the first bytes to disagree. |
|
2845 |
|
2846 @param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data |
|
2847 is to be compared with this Descriptor's data. |
|
2848 |
|
2849 @return Positive, if this descriptor is greater than the specified string. |
|
2850 Negative, if this descriptor is less than the specified string. |
|
2851 Zero, if both the descriptor and the string have the same length |
|
2852 and the their contents are the same. |
|
2853 */ |
|
2854 EXPORT_C TInt LString8::Compare(const TUint8* aZeroTerminatedString) const |
|
2855 { |
|
2856 return RBuf8::Compare(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
2857 } |
|
2858 /** |
|
2859 Compares this descriptor's folded data with the specified string's folded |
|
2860 data. |
|
2861 |
|
2862 Note that folding is locale-independent behaviour. It is also important to |
|
2863 note that there can be no guarantee that folding is in any way culturally |
|
2864 appropriate, and should not be used for comparing strings in natural language; |
|
2865 |
|
2866 @param aCharStr The 8-bit character string whose data is to be compared |
|
2867 with this Descriptor's data. |
|
2868 |
|
2869 @return Positive, if this descriptor is greater than the specified string. |
|
2870 Negative, if this descriptor is less than the specified string. |
|
2871 Zero, if the descriptor and the specified string have the same length |
|
2872 and the their contents are the same. |
|
2873 |
|
2874 @see TDesC8::Compare() |
|
2875 */ |
|
2876 EXPORT_C TInt LString8::CompareF(const char* aCharStr) const |
|
2877 { |
|
2878 return LString8::CompareF(reinterpret_cast<const TUint8*>(aCharStr)); |
|
2879 } |
|
2880 |
|
2881 /** |
|
2882 Compares this descriptor's folded data with the specified string's folded |
|
2883 data. |
|
2884 |
|
2885 Note that folding is locale-independent behaviour. It is also important to |
|
2886 note that there can be no guarantee that folding is in any way culturally |
|
2887 appropriate, and should not be used for comparing strings in natural language; |
|
2888 |
|
2889 @param aZeroTerminatedString The 8-bit Zero Terminated String whose data |
|
2890 is to be compared with this string's data. |
|
2891 |
|
2892 @return Positive, if this descriptor is greater than the specified string. |
|
2893 Negative, if this descriptor is less than the specified string. |
|
2894 Zero, if the descriptor and the specified string have the same length |
|
2895 and the their contents are the same. |
|
2896 |
|
2897 @see TDesC8::Compare() |
|
2898 */ |
|
2899 EXPORT_C TInt LString8::CompareF(const TUint8* aZeroTerminatedString) const |
|
2900 { |
|
2901 return RBuf8::CompareF(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
2902 } |
|
2903 |
|
2904 /** |
|
2905 Searches for the first occurrence of the specified data sequence within this |
|
2906 descriptor. |
|
2907 |
|
2908 Searching always starts at the beginning of this descriptor's data. |
|
2909 |
|
2910 @param aCharStr The 8-bit character string whose data is to be searched for, |
|
2911 within this Descriptor's data. |
|
2912 |
|
2913 @return The offset of the data sequence from the beginning of this descriptor's |
|
2914 data. KErrNotFound, if the data sequence cannot be found. |
|
2915 */ |
|
2916 EXPORT_C TInt LString8::Find(const char* aCharStr) const |
|
2917 { |
|
2918 return LString8::Find(reinterpret_cast<const TUint8*>(aCharStr)); |
|
2919 } |
|
2920 |
|
2921 /** |
|
2922 Searches for the first occurrence of the specified data sequence within this |
|
2923 descriptor. |
|
2924 |
|
2925 Searching always starts at the beginning of this descriptor's data. |
|
2926 |
|
2927 @param aCharStr The 8-bit character string whose data is to be searched for, |
|
2928 within this Descriptor's data. |
|
2929 |
|
2930 @return The offset of the data sequence from the beginning of this descriptor's |
|
2931 data. KErrNotFound, if the data sequence cannot be found. |
|
2932 */ |
|
2933 EXPORT_C TInt LString8::Find(const TUint8* aZeroTerminatedString) const |
|
2934 { |
|
2935 return RBuf8::Find(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
2936 } |
|
2937 |
|
2938 /** |
|
2939 Searches for the first occurrence of the specified data sequence within this |
|
2940 descriptor. |
|
2941 |
|
2942 Searching always starts at the beginning of this descriptor's data. |
|
2943 |
|
2944 @param aCharStr The 8-bit character string whose data is to be searched for, |
|
2945 within this Descriptor's data. |
|
2946 @param aLenS The length of the data sequence to be searched for. This value |
|
2947 must not be negative, otherwise the function raises a panic. |
|
2948 |
|
2949 @return The offset of the data sequence from the beginning of this descriptor's |
|
2950 data. KErrNotFound, if the data sequence cannot be found. |
|
2951 |
|
2952 @panic USER 29 if aLenS is negative. |
|
2953 */ |
|
2954 EXPORT_C TInt LString8::Find(const char* aCharStr,TInt aLenS) const |
|
2955 { |
|
2956 return LString8::Find(reinterpret_cast<const TUint8*>(aCharStr), aLenS); |
|
2957 } |
|
2958 |
|
2959 /** |
|
2960 Searches for the first occurrence of the specified folded data sequence within |
|
2961 this descriptor's folded data. |
|
2962 |
|
2963 Searching always starts at the beginning of this descriptor's data. |
|
2964 |
|
2965 Note that folding is locale-independent behaviour. It is also important to |
|
2966 note that there can be no guarantee that folding is in any way culturally |
|
2967 appropriate, and should not be used for finding strings in natural language; |
|
2968 |
|
2969 @param aCharStr The 8-bit character string whose data is to be searched for, |
|
2970 within this Descriptor's data. |
|
2971 |
|
2972 @return The offset of the data sequence from the beginning of this descriptor's |
|
2973 data. KErrNotFound, if the data sequence cannot be found. Zero, if the |
|
2974 length of the search data sequence is zero. |
|
2975 |
|
2976 */ |
|
2977 EXPORT_C TInt LString8::FindF(const char* aCharStr) const |
|
2978 { |
|
2979 return LString8::FindF(reinterpret_cast<const TUint8*>(aCharStr)); |
|
2980 } |
|
2981 |
|
2982 /** |
|
2983 Searches for the first occurrence of the specified folded data sequence within |
|
2984 this descriptor's folded data. |
|
2985 |
|
2986 Searching always starts at the beginning of this descriptor's data. |
|
2987 |
|
2988 Note that folding is locale-independent behaviour. It is also important to |
|
2989 note that there can be no guarantee that folding is in any way culturally |
|
2990 appropriate, and should not be used for finding strings in natural language; |
|
2991 |
|
2992 @param aCharStr The 8-bit character string whose data is to be searched for, |
|
2993 within this Descriptor's data. |
|
2994 |
|
2995 @return The offset of the data sequence from the beginning of this descriptor's |
|
2996 data. KErrNotFound, if the data sequence cannot be found. Zero, if the |
|
2997 length of the search data sequence is zero. |
|
2998 |
|
2999 */ |
|
3000 EXPORT_C TInt LString8::FindF(const TUint8* aZeroTerminatedString) const |
|
3001 { |
|
3002 return RBuf8::FindF(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
3003 } |
|
3004 /** |
|
3005 Searches for the first occurrence of the specified folded data sequence within |
|
3006 this descriptor's folded data. |
|
3007 |
|
3008 Searching always starts at the beginning of this descriptor's data. |
|
3009 |
|
3010 Note that folding is locale-independent behaviour. It is also important to |
|
3011 note that there can be no guarantee that folding is in any way culturally |
|
3012 appropriate, and should not be used for finding strings in natural language; |
|
3013 |
|
3014 @param aCharStr The 8-bit character string whose data is to be searched for, |
|
3015 within this Descriptor's data. |
|
3016 @param aLenS The length of the data sequence to be searched for. This value |
|
3017 must not be negative, otherwise the function raises a panic. |
|
3018 |
|
3019 @return The offset of the data sequence from the beginning of this descriptor's |
|
3020 data. KErrNotFound, if the data sequence cannot be found. Zero, if the |
|
3021 length of the search data sequence is zero. |
|
3022 |
|
3023 @panic USER 29 if aLenS is negative |
|
3024 |
|
3025 */ |
|
3026 EXPORT_C TInt LString8::FindF(const char* aCharStr, TInt aLen) const |
|
3027 { |
|
3028 return RBuf8::FindF(reinterpret_cast<const TUint8*>(aCharStr),aLen); |
|
3029 } |
|
3030 |
|
3031 /** |
|
3032 Copies and folds data from the specified string into this descriptor replacing |
|
3033 any existing data. |
|
3034 |
|
3035 The length of this descriptor is set to reflect the new |
|
3036 data. |
|
3037 |
|
3038 Note that folding is locale-independent behaviour. It is also important to |
|
3039 note that there can be no guarantee that folding is in any way culturally |
|
3040 appropriate, and should not be used when dealing with strings in natural |
|
3041 language. |
|
3042 |
|
3043 This leaving variant of the standard, non-leaving descriptor method |
|
3044 differs in that this operation may cause the string descriptor's heap |
|
3045 buffer to be reallocated in order to accommodate the new data. As a |
|
3046 result, MaxLength() and Ptr() may return different values afterwards, |
|
3047 and any existing raw pointers to into the descriptor data may be |
|
3048 invalidated. |
|
3049 |
|
3050 @param aCharStr A 8-bit character string |
|
3051 |
|
3052 @leave KErrNoMemory if the underlying buffer needs to be |
|
3053 grown and there are insufficient resources to do so |
|
3054 */ |
|
3055 EXPORT_C void LString8:: CopyFL(const char* aCharStr ) |
|
3056 { |
|
3057 LString8::CopyFL(reinterpret_cast<const TUint8*>(aCharStr)); |
|
3058 } |
|
3059 |
|
3060 /** |
|
3061 Copies and folds data from the specified string into this descriptor replacing |
|
3062 any existing data. |
|
3063 |
|
3064 The length of this descriptor is set to reflect the new |
|
3065 data. |
|
3066 |
|
3067 Note that folding is locale-independent behaviour. It is also important to |
|
3068 note that there can be no guarantee that folding is in any way culturally |
|
3069 appropriate, and should not be used when dealing with strings in natural |
|
3070 language. |
|
3071 |
|
3072 This leaving variant of the standard, non-leaving descriptor method |
|
3073 differs in that this operation may cause the string descriptor's heap |
|
3074 buffer to be reallocated in order to accommodate the new data. As a |
|
3075 result, MaxLength() and Ptr() may return different values afterwards, |
|
3076 and any existing raw pointers to into the descriptor data may be |
|
3077 invalidated. |
|
3078 |
|
3079 @param aZeroTerminatedString A 8-bit zero terminated string |
|
3080 |
|
3081 @leave KErrNoMemory if the underlying buffer needs to be |
|
3082 grown and there are insufficient resources to do so |
|
3083 */ |
|
3084 EXPORT_C void LString8:: CopyFL(const TUint8* aZeroTerminatedString ) |
|
3085 { |
|
3086 LString8::CopyFL(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
3087 } |
|
3088 |
|
3089 /** |
|
3090 Copies text from the specified string and converts it to lower case before |
|
3091 putting it into this descriptor, replacing any existing data. |
|
3092 |
|
3093 The length of this descriptor is set to reflect the new data. |
|
3094 |
|
3095 Conversion to lower case is implemented as appropriate to the current locale. |
|
3096 |
|
3097 This leaving variant of the standard, non-leaving descriptor method |
|
3098 differs in that this operation may cause the string descriptor's heap |
|
3099 buffer to be reallocated in order to accommodate the new data. As a |
|
3100 result, MaxLength() and Ptr() may return different values afterwards, |
|
3101 and any existing raw pointers to into the descriptor data may be |
|
3102 invalidated. |
|
3103 |
|
3104 @param aCharStr A 8-bit character string. |
|
3105 |
|
3106 @leave KErrNoMemory if the underlying buffer needs to be |
|
3107 grown and there are insufficient resources to do so |
|
3108 */ |
|
3109 EXPORT_C void LString8:: CopyLCL(const char* aCharStr) |
|
3110 { |
|
3111 LString8::CopyLCL(reinterpret_cast<const TUint8*>(aCharStr)); |
|
3112 } |
|
3113 |
|
3114 /** |
|
3115 Copies text from the specified string and converts it to lower case before |
|
3116 putting it into this descriptor, replacing any existing data. |
|
3117 |
|
3118 The length of this descriptor is set to reflect the new data. |
|
3119 |
|
3120 Conversion to lower case is implemented as appropriate to the current locale. |
|
3121 |
|
3122 This leaving variant of the standard, non-leaving descriptor method |
|
3123 differs in that this operation may cause the string descriptor's heap |
|
3124 buffer to be reallocated in order to accommodate the new data. As a |
|
3125 result, MaxLength() and Ptr() may return different values afterwards, |
|
3126 and any existing raw pointers to into the descriptor data may be |
|
3127 invalidated. |
|
3128 |
|
3129 @param aZeroTerminatedString A 8-bit zero terminated string. |
|
3130 |
|
3131 @leave KErrNoMemory if the underlying buffer needs to be |
|
3132 grown and there are insufficient resources to do so |
|
3133 */ |
|
3134 EXPORT_C void LString8:: CopyLCL(const TUint8* aZeroTerminatedString) |
|
3135 { |
|
3136 LString8::CopyLCL(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
3137 } |
|
3138 |
|
3139 /** |
|
3140 Copies text from the specified string and converts it to upper case before |
|
3141 putting it into this descriptor, replacing any existing data. |
|
3142 |
|
3143 The length of this descriptor is set to reflect the new data. |
|
3144 |
|
3145 Conversion to upper case is implemented as appropriate to the current locale. |
|
3146 |
|
3147 This leaving variant of the standard, non-leaving descriptor method |
|
3148 differs in that this operation may cause the string descriptor's heap |
|
3149 buffer to be reallocated in order to accommodate the new data. As a |
|
3150 result, MaxLength() and Ptr() may return different values afterwards, |
|
3151 and any existing raw pointers to into the descriptor data may be |
|
3152 invalidated. |
|
3153 |
|
3154 @param aCharStr A 8-bit character string. |
|
3155 |
|
3156 @leave KErrNoMemory if the underlying buffer needs to be |
|
3157 grown and there are insufficient resources to do so |
|
3158 */ |
|
3159 EXPORT_C void LString8:: CopyUCL(const char* aCharStr) |
|
3160 { |
|
3161 LString8::CopyUCL(reinterpret_cast<const TUint8*>(aCharStr)); |
|
3162 } |
|
3163 |
|
3164 /** |
|
3165 Copies text from the specified string and converts it to upper case before |
|
3166 putting it into this descriptor, replacing any existing data. |
|
3167 |
|
3168 The length of this descriptor is set to reflect the new data. |
|
3169 |
|
3170 Conversion to upper case is implemented as appropriate to the current locale. |
|
3171 |
|
3172 This leaving variant of the standard, non-leaving descriptor method |
|
3173 differs in that this operation may cause the string descriptor's heap |
|
3174 buffer to be reallocated in order to accommodate the new data. As a |
|
3175 result, MaxLength() and Ptr() may return different values afterwards, |
|
3176 and any existing raw pointers to into the descriptor data may be |
|
3177 invalidated. |
|
3178 |
|
3179 @param aZeroTerminatedString A 8-bit zero terminated string. |
|
3180 |
|
3181 @leave KErrNoMemory if the underlying buffer needs to be |
|
3182 grown and there are insufficient resources to do so |
|
3183 */ |
|
3184 EXPORT_C void LString8:: CopyUCL(const TUint8* aZeroTerminatedString) |
|
3185 { |
|
3186 LString8::CopyUCL(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
3187 } |
|
3188 |
|
3189 /** |
|
3190 Copies text from the specified string and capitalises it before putting |
|
3191 it into this descriptor, replacing any existing data. |
|
3192 |
|
3193 The length of this descriptor is set to reflect the new data. |
|
3194 |
|
3195 Capitalisation is implemented as appropriate to the current locale. |
|
3196 |
|
3197 This leaving variant of the standard, non-leaving descriptor method |
|
3198 differs in that this operation may cause the string descriptor's heap |
|
3199 buffer to be reallocated in order to accommodate the new data. As a |
|
3200 result, MaxLength() and Ptr() may return different values afterwards, |
|
3201 and any existing raw pointers to into the descriptor data may be |
|
3202 invalidated. |
|
3203 |
|
3204 @param aCharStr A 8-bit character string. |
|
3205 |
|
3206 @leave KErrNoMemory if the underlying buffer needs to be |
|
3207 grown and there are insufficient resources to do so |
|
3208 */ |
|
3209 EXPORT_C void LString8:: CopyCPL(const char* aCharStr) |
|
3210 { |
|
3211 LString8::CopyCPL(reinterpret_cast<const TUint8*>(aCharStr)); |
|
3212 } |
|
3213 |
|
3214 /** |
|
3215 Copies text from the specified string and capitalises it before putting |
|
3216 it into this descriptor, replacing any existing data. |
|
3217 |
|
3218 The length of this descriptor is set to reflect the new data. |
|
3219 |
|
3220 Capitalisation is implemented as appropriate to the current locale. |
|
3221 |
|
3222 This leaving variant of the standard, non-leaving descriptor method |
|
3223 differs in that this operation may cause the string descriptor's heap |
|
3224 buffer to be reallocated in order to accommodate the new data. As a |
|
3225 result, MaxLength() and Ptr() may return different values afterwards, |
|
3226 and any existing raw pointers to into the descriptor data may be |
|
3227 invalidated. |
|
3228 |
|
3229 @param aZeroTerminatedString A 8-bit zero terminated string. |
|
3230 |
|
3231 @leave KErrNoMemory if the underlying buffer needs to be |
|
3232 grown and there are insufficient resources to do so |
|
3233 */ |
|
3234 EXPORT_C void LString8:: CopyCPL(const TUint8* aZeroTerminatedString) |
|
3235 { |
|
3236 LString8::CopyCPL(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
3237 } |
|
3238 /** |
|
3239 Inserts data into this descriptor. |
|
3240 |
|
3241 The length of this descriptor is changed to reflect the extra data. |
|
3242 |
|
3243 This leaving variant of the standard, non-leaving descriptor method |
|
3244 differs in that this operation may cause the string descriptor's heap |
|
3245 buffer to be reallocated in order to accommodate the new data. As a |
|
3246 result, MaxLength() and Ptr() may return different values afterwards, |
|
3247 and any existing raw pointers to into the descriptor data may be |
|
3248 invalidated. |
|
3249 |
|
3250 @param aPos The position within the data where insertion is to start. This |
|
3251 is an offset value; a zero value refers to the leftmost data |
|
3252 position. |
|
3253 |
|
3254 @param aCharStr A 8-bit character string. |
|
3255 |
|
3256 @leave KErrNoMemory if the underlying buffer needs to be |
|
3257 grown and there are insufficient resources to do so |
|
3258 |
|
3259 @panic USER 10 if aPos is negative or is greater than the length of this |
|
3260 descriptor. |
|
3261 */ |
|
3262 EXPORT_C void LString8:: InsertL(TInt aPos,const char* aCharStr) |
|
3263 { |
|
3264 LString8::InsertL(aPos, reinterpret_cast<const TUint8*>(aCharStr)); |
|
3265 } |
|
3266 |
|
3267 /** |
|
3268 Inserts data into this descriptor. |
|
3269 |
|
3270 The length of this descriptor is changed to reflect the extra data. |
|
3271 |
|
3272 This leaving variant of the standard, non-leaving descriptor method |
|
3273 differs in that this operation may cause the string descriptor's heap |
|
3274 buffer to be reallocated in order to accommodate the new data. As a |
|
3275 result, MaxLength() and Ptr() may return different values afterwards, |
|
3276 and any existing raw pointers to into the descriptor data may be |
|
3277 invalidated. |
|
3278 |
|
3279 @param aPos The position within the data where insertion is to start. This |
|
3280 is an offset value; a zero value refers to the leftmost data |
|
3281 position. |
|
3282 |
|
3283 @param aZeroTerminatedString A 8-bit null terminated string. |
|
3284 |
|
3285 @leave KErrNoMemory if the underlying buffer needs to be |
|
3286 grown and there are insufficient resources to do so |
|
3287 |
|
3288 @panic USER 10 if aPos is negative or is greater than the length of this |
|
3289 descriptor. |
|
3290 */ |
|
3291 EXPORT_C void LString8:: InsertL(TInt aPos,const TUint8* aZeroTerminatedString) |
|
3292 { |
|
3293 LString8::InsertL(aPos,TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
3294 } |
|
3295 |
|
3296 /** |
|
3297 Replaces data in this descriptor. |
|
3298 |
|
3299 The specified length can be different to the length of the replacement data. |
|
3300 The length of this descriptor changes to reflect the change of data. |
|
3301 |
|
3302 This leaving variant of the standard, non-leaving descriptor method |
|
3303 differs in that this operation may cause the string descriptor's heap |
|
3304 buffer to be reallocated in order to accommodate the new data. As a |
|
3305 result, MaxLength() and Ptr() may return different values afterwards, |
|
3306 and any existing raw pointers to into the descriptor data may be |
|
3307 invalidated. |
|
3308 |
|
3309 @param aPos The position within the data where replacement is to start. |
|
3310 This is an offset value; a zero value refers to the leftmost |
|
3311 data position. |
|
3312 |
|
3313 @param aLength The length of data to be replaced. |
|
3314 |
|
3315 @param aCharStr The source 8-bit character string |
|
3316 |
|
3317 @leave KErrNoMemory if the underlying buffer needs to be |
|
3318 grown and there are insufficient resources to do so |
|
3319 |
|
3320 @panic USER 8 if aLength is negative |
|
3321 |
|
3322 @panic USER 10 if aPos is negative or is greater than the length of this |
|
3323 descriptor. |
|
3324 |
|
3325 @panic USER 16 if the length of the source descriptor aDes is negative |
|
3326 */ |
|
3327 EXPORT_C void LString8:: ReplaceL(TInt aPos,TInt aLength,const char* aCharStr) |
|
3328 { |
|
3329 LString8::ReplaceL(aPos,aLength,reinterpret_cast<const TUint8*>(aCharStr)); |
|
3330 } |
|
3331 |
|
3332 /** |
|
3333 Replaces data in this descriptor. |
|
3334 |
|
3335 The specified length can be different to the length of the replacement data. |
|
3336 The length of this descriptor changes to reflect the change of data. |
|
3337 |
|
3338 This leaving variant of the standard, non-leaving descriptor method |
|
3339 differs in that this operation may cause the string descriptor's heap |
|
3340 buffer to be reallocated in order to accommodate the new data. As a |
|
3341 result, MaxLength() and Ptr() may return different values afterwards, |
|
3342 and any existing raw pointers to into the descriptor data may be |
|
3343 invalidated. |
|
3344 |
|
3345 @param aPos The position within the data where replacement is to start. |
|
3346 This is an offset value; a zero value refers to the leftmost |
|
3347 data position. |
|
3348 |
|
3349 @param aLength The length of data to be replaced. |
|
3350 |
|
3351 @param aZeroTerminatedString The source 8-bit null terminated character string |
|
3352 |
|
3353 @leave KErrNoMemory if the underlying buffer needs to be |
|
3354 grown and there are insufficient resources to do so |
|
3355 |
|
3356 @panic USER 8 if aLength is negative |
|
3357 |
|
3358 @panic USER 10 if aPos is negative or is greater than the length of this |
|
3359 descriptor. |
|
3360 |
|
3361 @panic USER 16 if the length of the source descriptor aDes is negative |
|
3362 */ |
|
3363 EXPORT_C void LString8:: ReplaceL(TInt aPos,TInt aLength,const TUint8* aZeroTerminatedString) |
|
3364 { |
|
3365 LString8::ReplaceL(aPos,aLength,TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString))); |
|
3366 } |
|
3367 |
|
3368 /** |
|
3369 Copies data into this descriptor and justifies it, replacing any existing data. |
|
3370 |
|
3371 The length of this descriptor is set to reflect the new data. |
|
3372 |
|
3373 The target area is considered to be an area of specified width positioned at |
|
3374 the beginning of this descriptor's data area. Source data is copied into, and |
|
3375 aligned within this target area according to the specified alignment |
|
3376 instruction. |
|
3377 |
|
3378 If the length of the target area is larger than the length of the source, then |
|
3379 spare space within the target area is padded with the fill character. |
|
3380 |
|
3381 This leaving variant of the standard, non-leaving descriptor method |
|
3382 differs in that this operation may cause the string descriptor's heap |
|
3383 buffer to be reallocated in order to accommodate the new data. As a |
|
3384 result, MaxLength() and Ptr() may return different values afterwards, |
|
3385 and any existing raw pointers to into the descriptor data may be |
|
3386 invalidated. |
|
3387 |
|
3388 @param aCharStr A 8-bit character string containing the source data. |
|
3389 The length of the data to be copied is the smaller of: |
|
3390 the length of the source descriptor, and |
|
3391 the width of the target area (only if this is not the |
|
3392 explicit negative value KDefaultJustifyWidth). |
|
3393 |
|
3394 @param aWidth The width of the target area. If this has the specific |
|
3395 negative value KDefaultJustifyWidth, then the width is |
|
3396 re-set to the length of the data source. |
|
3397 |
|
3398 @param aAlignment The alignment of the data within the target area |
|
3399 |
|
3400 @param aFill The fill character used to pad the target area. |
|
3401 |
|
3402 @leave KErrNoMemory if the underlying buffer needs to be |
|
3403 grown and there are insufficient resources to do so |
|
3404 |
|
3405 @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. |
|
3406 */ |
|
3407 EXPORT_C void LString8:: JustifyL(const char* aCharStr,TInt aWidth,TAlign anAlignment,TChar aFill) |
|
3408 { |
|
3409 LString8::JustifyL(reinterpret_cast<const TUint8*>(aCharStr),aWidth,anAlignment,aFill); |
|
3410 } |
|
3411 |
|
3412 /** |
|
3413 Copies data into this descriptor and justifies it, replacing any existing data. |
|
3414 |
|
3415 The length of this descriptor is set to reflect the new data. |
|
3416 |
|
3417 The target area is considered to be an area of specified width positioned at |
|
3418 the beginning of this descriptor's data area. Source data is copied into, and |
|
3419 aligned within this target area according to the specified alignment |
|
3420 instruction. |
|
3421 |
|
3422 If the length of the target area is larger than the length of the source, then |
|
3423 spare space within the target area is padded with the fill character. |
|
3424 |
|
3425 This leaving variant of the standard, non-leaving descriptor method |
|
3426 differs in that this operation may cause the string descriptor's heap |
|
3427 buffer to be reallocated in order to accommodate the new data. As a |
|
3428 result, MaxLength() and Ptr() may return different values afterwards, |
|
3429 and any existing raw pointers to into the descriptor data may be |
|
3430 invalidated. |
|
3431 |
|
3432 @param aCharStr A 8-bit character string containing the source data. |
|
3433 The length of the data to be copied is the smaller of: |
|
3434 the length of the source descriptor, and |
|
3435 the width of the target area (only if this is not the |
|
3436 explicit negative value KDefaultJustifyWidth). |
|
3437 |
|
3438 @param aWidth The width of the target area. If this has the specific |
|
3439 negative value KDefaultJustifyWidth, then the width is |
|
3440 re-set to the length of the data source. |
|
3441 |
|
3442 @param aAlignment The alignment of the data within the target area |
|
3443 |
|
3444 @param aFill The fill character used to pad the target area. |
|
3445 |
|
3446 @leave KErrNoMemory if the underlying buffer needs to be |
|
3447 grown and there are insufficient resources to do so |
|
3448 |
|
3449 @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. |
|
3450 */ |
|
3451 EXPORT_C void LString8:: JustifyL(const TUint8* aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill) |
|
3452 { |
|
3453 LString8::JustifyL(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)),aWidth,anAlignment,aFill); |
|
3454 } |
|
3455 |
|
3456 /** |
|
3457 Appends data onto the end of this descriptor's data and justifies it. |
|
3458 |
|
3459 The source of the appended data is a memory location. |
|
3460 |
|
3461 The target area is considered to be an area of specified width, immediately |
|
3462 following this descriptor's existing data. Source data is copied into, and |
|
3463 aligned within, this target area according to the specified alignment instruction. |
|
3464 |
|
3465 If the length of the target area is larger than the length of the source, |
|
3466 then spare space within the target area is padded with the fill character. |
|
3467 |
|
3468 This leaving variant of the standard, non-leaving descriptor method |
|
3469 differs in that this operation may cause the string descriptor's heap |
|
3470 buffer to be reallocated in order to accommodate the new data. As a |
|
3471 result, MaxLength() and Ptr() may return different values afterwards, |
|
3472 and any existing raw pointers to into the descriptor data may be |
|
3473 invalidated. |
|
3474 |
|
3475 @param aString A pointer to a source memory location. |
|
3476 |
|
3477 @param aLength The length of data to be copied. If this is greater than the |
|
3478 width of the target area, then the length of data copied is |
|
3479 limited to the width. |
|
3480 |
|
3481 @param aWidth The width of the target area. If this has the specific negative |
|
3482 value KDefaultJustifyWidth, then the width is |
|
3483 re-set to the length of the data source. |
|
3484 |
|
3485 @param aAlignment The alignment of the data within the target area. |
|
3486 |
|
3487 @param aFill The fill character used to pad the target area. |
|
3488 |
|
3489 @leave KErrNoMemory if the underlying buffer needs to be |
|
3490 grown and there are insufficient resources to do so |
|
3491 |
|
3492 @panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth. |
|
3493 |
|
3494 @panic USER 17 if aLength is negative. |
|
3495 */ |
|
3496 EXPORT_C void LString8:: AppendJustifyL(const char* aCharStr,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill) |
|
3497 { |
|
3498 LString8::AppendJustifyL(reinterpret_cast<const TUint8*>(aCharStr),aLength, aWidth,anAlignment,aFill); |
|
3499 } |
|
3500 |
|
3501 // eof |