1 // Copyright (c) 1995-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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
5 // which accompanies this distribution, and is available
6 // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
8 // Initial Contributors:
9 // Nokia Corporation - initial contribution.
14 // e32\include\e32des16.h
18 #ifndef __E32DES16_H__
19 #define __E32DES16_H__
24 const TUint KMaskDesLength16=0xfffffff;
28 const TInt KShiftDesType16=28;
34 struct TCollationMethod;
43 Abstract base class for 16-bit descriptors.
45 The class encapsulates the data member containing the length of data
46 represented by a 16-bit descriptor. It also provides member functions through
47 which the data can be accessed, but not modified.
49 Data represented by this class is treated as a contiguous set of 16-bit (i.e.
50 double byte) values or data items.
52 This class cannot be instantiated as it is intended to form part of a class
53 hierarchy; it provides a well defined part of descriptor behaviour. It can,
54 however, be passed as an argument type for functions which want access to
55 descriptor data but do not need to modify that data.
63 A value returned by a call to HasPrefixC().
65 @see TDesC16::HasPrefixC
69 Indicates that a supplied prefix can be extended to
70 be equivalent to the text at the start of a descriptor.
74 Indicates that a supplied prefix does not seem to be a
75 prefix, but it is possible that it could be extended to
76 become equivalent to text at the start of this descriptor.
80 Indicates that a supplied prefix cannot be extended to be
81 equivalent to the text at the start of a descriptor.
86 inline TBool operator<(const TDesC16 &aDes) const;
87 inline TBool operator<=(const TDesC16 &aDes) const;
88 inline TBool operator>(const TDesC16 &aDes) const;
89 inline TBool operator>=(const TDesC16 &aDes) const;
90 inline TBool operator==(const TDesC16 &aDes) const;
91 inline TBool operator!=(const TDesC16 &aDes) const;
92 inline const TUint16 &operator[](TInt anIndex) const;
93 inline TInt Length() const;
94 inline TInt Size() const;
95 IMPORT_C const TUint16 *Ptr() const;
96 IMPORT_C TInt Compare(const TDesC16 &aDes) const;
97 IMPORT_C TInt CompareF(const TDesC16 &aDes) const;
98 IMPORT_C TInt CompareC(const TDesC16 &aDes) const;
99 IMPORT_C TInt CompareC(const TDesC16& aDes,TInt aMaxLevel,const TCollationMethod* aCollationMethod) const;
103 IMPORT_C HBufC16* GetNormalizedDecomposedFormL() const;
107 IMPORT_C HBufC16* GetFoldedDecomposedFormL() const;
111 IMPORT_C HBufC8* GetCollationKeysL(TInt aMaxLevel,const TCollationMethod* aCollationMethod) const;
112 IMPORT_C TInt Match(const TDesC16 &aDes) const;
113 IMPORT_C TInt MatchF(const TDesC16 &aDes) const;
114 IMPORT_C TInt MatchC(const TDesC16 &aDes) const;
115 IMPORT_C TInt MatchC(const TDesC16 &aPattern, TInt aWildChar, TInt aWildSequenceChar,
116 TInt aEscapeChar, TInt aMaxLevel = 3, const TCollationMethod* aCollationMethod = NULL) const;
117 IMPORT_C TInt MatchC(const TDesC16 &aPattern, const TCollationMethod* aCollationMethod,
118 TInt aMaxLevel = 3, TInt aWildChar = '?', TInt aWildSequenceChar = '*', TInt aEscapeChar = 0) const;
119 IMPORT_C TInt Locate(TChar aChar) const;
120 IMPORT_C TInt LocateReverse(TChar aChar) const;
121 IMPORT_C TInt Find(const TDesC16 &aDes) const;
122 IMPORT_C TInt Find(const TUint16 *aBuf,TInt aLen) const;
123 IMPORT_C TPrefix HasPrefixC(const TDesC16& aPossiblePrefix, TInt aLevel, const TCollationMethod* aCollationMethod) const;
124 IMPORT_C TPtrC16 Left(TInt aLength) const;
125 IMPORT_C TPtrC16 Right(TInt aLength) const;
126 IMPORT_C TPtrC16 Mid(TInt aPos) const;
127 IMPORT_C TPtrC16 Mid(TInt aPos,TInt aLength) const;
128 IMPORT_C TInt LocateF(TChar aChar) const;
129 IMPORT_C TInt LocateReverseF(TChar aChar) const;
130 IMPORT_C TInt FindF(const TDesC16 &aDes) const;
131 IMPORT_C TInt FindF(const TUint16 *aBuf,TInt aLen) const;
132 IMPORT_C TInt FindC(const TDesC16 &aDes) const;
133 IMPORT_C TInt FindC(const TUint16 *aBuf,TInt aLen) const;
134 IMPORT_C TInt FindC(const TUint16 *aText,TInt aLength, TInt aMaxLevel) const;
135 IMPORT_C TInt FindC(const TDesC16 &aDes,TInt &aLengthFound, const TCollationMethod &aMethod,TInt aMaxLevel) const;
136 IMPORT_C HBufC16 *Alloc() const;
137 IMPORT_C HBufC16 *AllocL() const;
138 IMPORT_C HBufC16 *AllocLC() const;
141 inline TDesC16(TInt aType,TInt aLength);
142 // delay this for a while
143 #ifdef SYMBIAN_FIX_TDESC_CONSTRUCTORS
144 inline TDesC16( const TDesC16& aOther) : iLength(aOther.iLength) {}
146 // inline ~TDesC16() {} Commented out for the moment since it breaks code
147 inline TInt Type() const;
148 inline void DoSetLength(TInt aLength);
149 IMPORT_C const TUint16 &AtC(TInt anIndex) const;
155 class TPtrC16 : public TDesC16
160 16-bit non-modifiable pointer descriptor.
162 This is a descriptor class intended for instantiation and encapsulates a
163 pointer to the 16-bit data that it represents. The data can live in ROM or RAM
164 and this location is separate from the descriptor object itself.
166 The data is intended to be accessed, but not changed, through this descriptor.
167 The base class provides the functions through which data is accessed.
179 IMPORT_C TPtrC16(const TDesC16 &aDes);
180 IMPORT_C TPtrC16(const TUint16 *aString);
181 IMPORT_C TPtrC16(const TUint16 *aBuf,TInt aLength);
182 inline void Set(const TUint16 *aBuf,TInt aLength);
183 inline void Set(const TDesC16 &aDes);
184 inline void Set(const TPtrC16 &aPtr);
186 TPtrC16& operator=(const TPtrC16 &aDes);
198 An interface that defines an overflow handler for a 16-bit descriptor.
200 The interface encapsulates a function that is called when an attempt to append
201 formatted text fails because the descriptor is already at its maximum length.
203 A derived class must provide an implementation for the Overflow() member function.
205 @see TDes16::AppendFormat
210 Handles the overflow.
212 This function is called when the TDes16::AppendFormat()
213 variant that takes an overflow handler argument, fails.
215 @param aDes The 16-bit modifiable descriptor whose overflow results in the
216 call to this overflow handler.
218 virtual void Overflow(TDes16 &aDes)=0;
221 class TDes16IgnoreOverflow : public TDes16Overflow
226 A derived class which provides an implementation for the Overflow() member function
227 where truncation is required.
229 @see TDes16::AppendFormat
234 Handles the overflow.
236 This function is called when the TDes16::AppendFormat()
237 variant that takes an overflow handler argument, fails.
239 @param aDes The 16-bit modifiable descriptor whose overflow results in the
240 call to this overflow handler.
242 IMPORT_C virtual void Overflow(TDes16 &aDes);
246 class TDes16 : public TDesC16
251 Abstract base class for 16-bit modifiable descriptors.
253 The class encapsulates the data member containing the maximum length of data
254 represented by a 16-bit descriptor. It also provides member functions through
255 which the data can be modified.
257 The class adds to the behaviour provided by TDesC16.
259 This class cannot be instantiated as it is intended to form part of a class
260 hierarchy; it provides a well defined part of descriptor behaviour. It can,
261 however, be passed as an argument type for functions which need to both modify
262 and access descriptor data.
270 inline TDes16& operator=(const TUint16 *aString);
271 inline TDes16& operator=(const TDesC16 &aDes);
272 inline TDes16& operator=(const TDes16 &aDes);
273 inline TInt MaxLength() const;
274 inline TInt MaxSize() const;
275 inline const TUint16 &operator[](TInt anIndex) const;
276 inline TUint16 &operator[](TInt anIndex);
277 inline TDes16 &operator+=(const TDesC16 &aDes);
278 IMPORT_C void Zero();
279 IMPORT_C void SetLength(TInt aLength);
280 IMPORT_C void SetMax();
281 IMPORT_C void Copy(const TDesC8 &aDes);
282 IMPORT_C void Copy(const TDesC16 &aDes);
283 IMPORT_C void Copy(const TUint16 *aBuf,TInt aLength);
284 IMPORT_C void Copy(const TUint16 *aString);
285 IMPORT_C void Append(TChar aChar);
286 IMPORT_C void Append(const TDesC16 &aDes);
287 IMPORT_C void Append(const TUint16 *aBuf,TInt aLength);
288 IMPORT_C void Fill(TChar aChar);
289 IMPORT_C void Fill(TChar aChar,TInt aLength);
290 IMPORT_C void FillZ();
291 IMPORT_C void FillZ(TInt aLength);
292 IMPORT_C void NumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth);
293 IMPORT_C void AppendNumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth);
294 IMPORT_C TPtr16 LeftTPtr(TInt aLength) const;
295 IMPORT_C TPtr16 RightTPtr(TInt aLength) const;
296 IMPORT_C TPtr16 MidTPtr(TInt aPos) const;
297 IMPORT_C TPtr16 MidTPtr(TInt aPos,TInt aLength) const;
298 IMPORT_C const TUint16 *PtrZ();
299 IMPORT_C void CopyF(const TDesC16 &aDes);
300 IMPORT_C void CopyC(const TDesC16 &aDes);
301 IMPORT_C void CopyLC(const TDesC16 &aDes);
302 IMPORT_C void CopyUC(const TDesC16 &aDes);
303 IMPORT_C void CopyCP(const TDesC16 &aDes);
304 IMPORT_C void AppendFill(TChar aChar,TInt aLength);
305 IMPORT_C void ZeroTerminate();
306 IMPORT_C void Swap(TDes16 &aDes);
307 IMPORT_C void Fold();
308 IMPORT_C void Collate();
309 IMPORT_C void LowerCase();
310 IMPORT_C void UpperCase();
311 IMPORT_C void Capitalize();
312 IMPORT_C void Repeat(const TDesC16 &aDes);
313 IMPORT_C void Repeat(const TUint16 *aBuf,TInt aLength);
314 IMPORT_C void Trim();
315 IMPORT_C void TrimAll();
316 IMPORT_C void TrimLeft();
317 IMPORT_C void TrimRight();
318 IMPORT_C void Insert(TInt aPos,const TDesC16 &aDes);
319 IMPORT_C void Delete(TInt aPos,TInt aLength);
320 IMPORT_C void Replace(TInt aPos,TInt aLength,const TDesC16 &aDes);
321 IMPORT_C void Justify(const TDesC16 &aDes,TInt aWidth,TAlign anAlignment,TChar aFill);
322 IMPORT_C void NumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth);
323 IMPORT_C void NumUC(TUint64 aVal, TRadix aRadix=EDecimal);
324 IMPORT_C TInt Num(TReal aVal,const TRealFormat &aFormat) __SOFTFP;
325 IMPORT_C void Num(TInt64 aVal);
326 IMPORT_C void Num(TUint64 aVal, TRadix aRadix);
327 IMPORT_C void Format(TRefByValue<const TDesC16> aFmt,...);
328 IMPORT_C void FormatList(const TDesC16 &aFmt,VA_LIST aList);
329 IMPORT_C void AppendJustify(const TDesC16 &Des,TInt aWidth,TAlign anAlignment,TChar aFill);
330 IMPORT_C void AppendJustify(const TDesC16 &Des,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);
331 IMPORT_C void AppendJustify(const TUint16 *aString,TInt aWidth,TAlign anAlignment,TChar aFill);
332 IMPORT_C void AppendJustify(const TUint16 *aString,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);
333 IMPORT_C void AppendNumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth);
334 IMPORT_C void AppendNumUC(TUint64 aVal, TRadix aRadix=EDecimal);
335 IMPORT_C TInt AppendNum(TReal aVal,const TRealFormat &aFormat) __SOFTFP;
336 IMPORT_C void AppendNum(TInt64 aVal);
337 IMPORT_C void AppendNum(TUint64 aVal, TRadix aRadix);
338 IMPORT_C void AppendFormat(TRefByValue<const TDesC16> aFmt,TDes16Overflow *aOverflowHandler,...);
339 IMPORT_C void AppendFormat(TRefByValue<const TDesC16> aFmt,...);
340 IMPORT_C void AppendFormatList(const TDesC16 &aFmt,VA_LIST aList,TDes16Overflow *aOverflowHandler=NULL);
341 IMPORT_C TPtr8 Collapse();
344 inline TDes16(TInt aType,TInt aLength,TInt aMaxLength);
345 // delay this for a while
346 #ifdef SYMBIAN_FIX_TDESC_CONSTRUCTORS
347 inline TDes16(const TDes16& aOther) : TDesC16(aOther), iMaxLength(aOther.iMaxLength) {}
349 inline TUint16 *WPtr() const;
350 void DoAppendNum(TUint64 aVal, TRadix aRadix, TUint aA, TInt aW);
351 void DoPadAppendNum(TInt aLength, TInt aW, const TUint8* aBuf);
357 class TPtr16 : public TDes16
362 16-bit modifiable pointer descriptor
364 This is a descriptor class intended for instantiation and encapsulates a
365 pointer to the 16-bit data that it represents. The data can live in ROM or
366 RAM and this location is separate from the descriptor object itself.
368 The data is intended to be accessed and modified through this descriptor.
369 The base classes provide the functions through which the data can be
382 IMPORT_C TPtr16(TUint16 *aBuf,TInt aMaxLength);
383 IMPORT_C TPtr16(TUint16 *aBuf,TInt aLength,TInt aMaxLength);
384 inline TPtr16& operator=(const TUint16 *aString);
385 inline TPtr16& operator=(const TDesC16& aDes);
386 inline TPtr16& operator=(const TPtr16& aDes);
387 inline void Set(TUint16 *aBuf,TInt aLength,TInt aMaxLength);
388 inline void Set(const TPtr16 &aPtr);
390 IMPORT_C TPtr16(TBufCBase16 &aLcb,TInt aMaxLength);
394 friend class TBufCBase16;
398 class TBufCBase16 : public TDesC16
404 IMPORT_C TBufCBase16();
405 inline TBufCBase16(TInt aLength);
406 IMPORT_C TBufCBase16(const TUint16 *aString,TInt aMaxLength);
407 IMPORT_C TBufCBase16(const TDesC16 &aDes,TInt aMaxLength);
408 IMPORT_C void Copy(const TUint16 *aString,TInt aMaxLength);
409 IMPORT_C void Copy(const TDesC16 &aDes,TInt aMaxLength);
410 inline TPtr16 DoDes(TInt aMaxLength);
411 inline TUint16 *WPtr() const;
415 class HBufC16 : public TBufCBase16
420 16-bit heap descriptor.
422 This is a descriptor class which provides a buffer of fixed length, allocated
423 on the heap, for containing and accessing data.
425 The class is intended for instantiation.
427 Heap descriptors have the important property that they can be made larger
428 or smaller, changing the size of the descriptor buffer. This is achieved by
429 reallocating the descriptor. Unlike the behaviour of dynamic buffers, reallocation
430 is not done automatically.
432 Data is intended to be accessed, but not modified; however, it can be completely
433 replaced using the assignment operators of this class. The base class (TDesC16) provides
434 the functions through which the data is accessed.
436 The descriptor is hosted by a heap cell, and the 16-bit data that the descriptor
437 represents is part of the descriptor object itself. The size of the cell depends
438 on the requested maximum length of the descriptor buffer when the descriptor
439 is created or re-allocated.
441 It is important to note that the size of the allocated cell, and, therefore,
442 the resulting maximum length of the descriptor, may be larger than requested
443 due to the way memory is allocated in Symbian OS. The amount by which this
444 may be rounded up depends on the platform and build type.
452 IMPORT_C static HBufC16 *New(TInt aMaxLength);
453 IMPORT_C static HBufC16 *NewL(TInt aMaxLength);
454 IMPORT_C static HBufC16 *NewLC(TInt aMaxLength);
455 IMPORT_C static HBufC16 *NewMax(TInt aMaxLength);
456 IMPORT_C static HBufC16 *NewMaxL(TInt aMaxLength);
457 IMPORT_C static HBufC16 *NewMaxLC(TInt aMaxLength);
458 IMPORT_C static HBufC16 *NewL(RReadStream &aStream,TInt aMaxLength);
459 IMPORT_C static HBufC16 *NewLC(RReadStream &aStream,TInt aMaxLength);
460 IMPORT_C HBufC16& operator=(const TUint16 *aString);
461 IMPORT_C HBufC16& operator=(const TDesC16 &aDes);
462 inline HBufC16& operator=(const HBufC16 &aLcb);
463 IMPORT_C HBufC16 *ReAlloc(TInt aMaxLength);
464 IMPORT_C HBufC16 *ReAllocL(TInt aMaxLength);
465 IMPORT_C TPtr16 Des();
467 inline HBufC16(TInt aLength);
476 #define __Size16 (sizeof(TInt)/sizeof(TInt16))
480 #define __Align16(s) ((((s)+__Size16-1)/__Size16)*__Size16)
483 class TBufC16 : public TBufCBase16
488 16-bit non-modifiable buffer descriptor.
490 This is a descriptor class which provides a buffer of fixed length for
491 containing and accessing TUint16 data.
493 The class intended for instantiation. The 16-bit data that the descriptor
494 represents is part of the descriptor object itself.
496 The class is templated, based on an integer value which defines the size of
497 the descriptor's data area.
499 The data is intended to be accessed, but not modified; however, it can be
500 completely replaced using the assignment operators of this class. The base
501 class provides the functions through which the data is accessed.
511 inline TBufC16(const TUint16 *aString);
512 inline TBufC16(const TDesC16 &aDes);
513 inline TBufC16<S> &operator=(const TUint16 *aString);
514 inline TBufC16<S> &operator=(const TDesC16 &aDes);
517 TUint16 iBuf[__Align16(S)];
520 class TBufBase16 : public TDes16
526 IMPORT_C TBufBase16(TInt aMaxLength);
527 IMPORT_C TBufBase16(TInt aLength,TInt aMaxLength);
528 IMPORT_C TBufBase16(const TUint16* aString,TInt aMaxLength);
529 IMPORT_C TBufBase16(const TDesC16& aDes,TInt aMaxLength);
533 class TBuf16 : public TBufBase16
538 A descriptor class which provides a buffer of fixed length for
539 containing, accessing and manipulating TUint16 data.
541 The class is intended for instantiation. The 16-bit data that the descriptor
542 represents is part of the descriptor object itself.
544 The class is templated, based on an integer value which determines the size
545 of the data area which is created as part of the buffer descriptor object;
546 this is also the maximum length of the descriptor.
548 The data is intended to be both accessed and modified. The base classes provide
549 the functions through which the data is accessed.
559 inline explicit TBuf16(TInt aLength);
560 inline TBuf16(const TUint16* aString);
561 inline TBuf16(const TDesC16& aDes);
562 inline TBuf16<S>& operator=(const TUint16* aString);
563 inline TBuf16<S>& operator=(const TDesC16& aDes);
564 inline TBuf16<S>& operator=(const TBuf16<S>& aDes);
566 TUint16 iBuf[__Align16(S)];
570 #ifndef __KERNEL_MODE__
572 class RBuf16 : public TDes16
577 16 bit resizable buffer descriptor.
579 The class provides a buffer that contains, accesses and manipulates
580 TUint16 data. The buffer itself is on the heap, and is managed by the class.
582 Internally, RBuf16 behaves in one of two ways:
584 - as a TPtr16 descriptor type, where the buffer just contains data
585 - as a pointer to a heap descriptor, an HBufC16* type, where the buffer
586 contains both descriptor information and the data.
588 Note that the handling of the distinction is hidden from view.
590 An RBuf16 object can allocate its own buffer. Alternatively, it can take
591 ownership of a pre-existing section of allocated memory, or it can take
592 ownership of a pre-existing heap descriptor. It can also reallocate the buffer
593 to resize it. Regardless of the way in which the buffer has been allocated,
594 the RBuf16 object is responsible for freeing memory when the object itself is closed.
596 The class is intended for instantiation.
598 The class is derived from TDes16, which means that data can be both accessed
599 and modified. The base classes provide the functions through which the data is
600 accessed. In addition, an RBuf16 object can be passed to any function that is
601 prototyped to take a TDes16 or a TDesC16 type.
612 IMPORT_C explicit RBuf16(HBufC16* aHBuf);
613 inline RBuf16& operator=(const TUint16* aString);
614 inline RBuf16& operator=(const TDesC16& aDes);
615 inline RBuf16& operator=(const RBuf16& aDes);
616 IMPORT_C void Assign(const RBuf16& aRBuf);
617 IMPORT_C void Assign(TUint16 *aHeapCell,TInt aMaxLength);
618 IMPORT_C void Assign(TUint16 *aHeapCell,TInt aLength,TInt aMaxLength);
619 IMPORT_C void Assign(HBufC16* aHBuf);
620 IMPORT_C void Swap(RBuf16& aRBuf);
621 IMPORT_C TInt Create(TInt aMaxLength);
622 IMPORT_C void CreateL(TInt aMaxLength);
623 IMPORT_C TInt CreateMax(TInt aMaxLength);
624 IMPORT_C void CreateMaxL(TInt aMaxLength);
625 inline void CreateL(RReadStream &aStream,TInt aMaxLength);
626 IMPORT_C TInt Create(const TDesC16& aDes);
627 IMPORT_C void CreateL(const TDesC16& aDes);
628 IMPORT_C TInt Create(const TDesC16& aDes,TInt aMaxLength);
629 IMPORT_C void CreateL(const TDesC16& aDes,TInt aMaxLength);
630 IMPORT_C TInt ReAlloc(TInt aMaxLength);
631 IMPORT_C void ReAllocL(TInt aMaxLength);
632 IMPORT_C void Close();
633 IMPORT_C void CleanupClosePushL();
636 IMPORT_C RBuf16(TInt aType,TInt aLength,TInt aMaxLength);
637 RBuf16(const RBuf16&); // Outlaw copy construction
640 TUint16* iEPtrType; //Pointer to data used when RBuf is of EPtr type
641 HBufC16* iEBufCPtrType; //Pointer to data used when RBuf is of EBufCPtr type
646 #endif //__KERNEL_MODE__
653 Value reference used in operator TLitC16::__TRefDesC16()
657 typedef TRefByValue<const TDesC16> __TRefDesC16;
668 Encapsulates literal text.
670 This is always constructed using an _LIT16 macro.
672 This class is build independent; i.e. an explicit 16-bit build variant
673 is generated for both a non-Unicode build and a Unicode build.
675 The class has no explicit constructors.
681 inline const TDesC16* operator&() const;
682 inline operator const TDesC16&() const;
683 inline const TDesC16& operator()() const;
684 inline operator const __TRefDesC16() const;
686 #if defined(__GCC32__)
690 typedef wchar_t __TText;
691 #elif defined(__VC32__)
695 typedef TUint16 __TText;
696 #elif defined(__CW32__)
700 typedef TUint16 __TText;
701 #elif !defined(__TText_defined)
702 #error no typedef for __TText
713 __TText iBuf[__Align16(S)];