sl@0: // Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies). sl@0: // All rights reserved. sl@0: // This component and the accompanying materials are made available sl@0: // under the terms of "Eclipse Public License v1.0" sl@0: // which accompanies this distribution, and is available sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html". sl@0: // sl@0: // Initial Contributors: sl@0: // Nokia Corporation - initial contribution. sl@0: // sl@0: // Contributors: sl@0: // sl@0: // Description: sl@0: // sl@0: sl@0: #ifndef ESTRING_H sl@0: #define ESTRING_H sl@0: sl@0: #include sl@0: sl@0: // this macro is defined only if the target is WINSCW and wchar_t is ON sl@0: // (i.e OPTION CW -wchar_t on) sl@0: // and if the target is any thing other than WINSCW sl@0: // it is being assumed that wchar_t is ON(OPTION CW -wchar_t on by sl@0: // default or other wise) sl@0: #define NATIVE_WCHAR // most platforms do wchar_t properly sl@0: #if defined __cplusplus && defined __WINSCW__ sl@0: #if !__option(wchar_type) // without the wchar_type option sl@0: typedef unsigned short wchar_t; // needs a typedef sl@0: #undef NATIVE_WCHAR // which is not native sl@0: #endif sl@0: #endif sl@0: sl@0: // Since the LStrings can leave in their constructors, we have to make sl@0: // sure to avoid the operator new/delete ELeave mismatch problem that sl@0: // can result in the top level LString object heap being sl@0: // leaked. These operator delete overloads match the global operator sl@0: // new overloads applicable to the LString classes (which are sl@0: // non-CBase derived). sl@0: // sl@0: // Note that when allocating a native C++ array of LStrings, only the sl@0: // default constructor is invoked which cannot leave. So there are no sl@0: // issues related to the array case. sl@0: sl@0: #define LSTRING_CONSTRUCTORS_MAY_LEAVE \ sl@0: static void operator delete(TAny* aPtr) __NO_THROW \ sl@0: { \ sl@0: return ::operator delete(aPtr); \ sl@0: } \ sl@0: \ sl@0: static void operator delete(TAny* aPtr, TLeave) __NO_THROW \ sl@0: { \ sl@0: return ::operator delete(aPtr); \ sl@0: } \ sl@0: \ sl@0: static void operator delete(TAny*, TAny*) __NO_THROW \ sl@0: { \ sl@0: } sl@0: sl@0: /** sl@0: @file sl@0: sl@0: A self-managing descriptor class sl@0: sl@0: @publishedAll sl@0: @released sl@0: */ sl@0: sl@0: /** sl@0: @class LString8 sl@0: sl@0: LString8 is a convenient, general-purpose 8 bit string class derived sl@0: from RBuf8. LString8 adds automatic cleanup and on-demand buffer sl@0: resize facilities. sl@0: sl@0: @par L-Classes sl@0: sl@0: Note: The L prefix denotes that construction, copying, passing and sl@0: returning by value, assignment, and manipulation via operators should sl@0: all be considered potentially leaving operations unless otherwise sl@0: explicitly documented. Code that uses LString8 should be written sl@0: accordingly, in leave-safe style. sl@0: sl@0: @par Descriptor Relationships sl@0: sl@0: Like an RBuf8, an LString8 can be passed to any function that is sl@0: prototyped to take a TDes8 or a TDesC8 reference. Again like an sl@0: RBuf8, an LString8 maintains its string data in a heap buffer. sl@0: sl@0: @par Value-Type Behaviour sl@0: sl@0: Unlike RBuf8, an LString8 may be used much like a simple T class; sl@0: LString8 typed variables will automatically clean up after themselves sl@0: when they go out of scope, and LString8 typed fields will similarly sl@0: automatically release all owned resources when their containing object sl@0: is destroyed. sl@0: sl@0: For example, where: sl@0: sl@0: @code sl@0: RBuf8 buf; sl@0: buf.CleanupClosePushL(); sl@0: ... sl@0: CleanupStack::PopAndDestroy(); sl@0: @endcode sl@0: sl@0: would be required, with LString8: sl@0: sl@0: @code sl@0: LString8 buf; sl@0: ... sl@0: @endcode sl@0: sl@0: will suffice. Pushing an LString8 onto the cleanup stack is not sl@0: necessary or recommended, but the effects of doing so are sl@0: benign. LString8 instances can also be passed and returned by value, sl@0: but note that doing so may trigger implicit heap allocation and cause sl@0: a leave with KErrNoMemory. sl@0: sl@0: @code sl@0: void TakeString(LString8 aString) sl@0: { sl@0: // ... sl@0: } sl@0: sl@0: LString8 ReturnString(LString8 aString) sl@0: { sl@0: TakeString(aString); // Statement may leave with KErrNoMemory sl@0: return aString; // Statement may leave with KErrNoMemory sl@0: } sl@0: @endcode sl@0: sl@0: As with other descriptors, passing by reference when possible is more sl@0: efficient. sl@0: sl@0: @par On-Demand Growth sl@0: sl@0: In addition to the value-type semantics described above, LString8 sl@0: also supports automatic in-place resizing. All standard descriptor sl@0: methods are available, but for any non-leaving descriptor method that sl@0: may panic due to buffer overflow, LString8 adds a corresponding sl@0: leaving method that automatically expands the underlying buffer sl@0: on-demand. For example, Append() will panic if the new data overflows sl@0: available buffer space, while AppendL() will attempt to realloc the sl@0: buffer as necessary. The new leaving variants may therefore leave with sl@0: KErrNoMemory, may invalidate any existing raw pointers into the data sl@0: buffer (e.g. those previously returned by Ptr()), and may change the sl@0: value returned by MaxLength(). sl@0: sl@0: @code sl@0: LString8 message; // Zero length sl@0: message.FormatL(_L("This is message %n from %S"), n, &s); // FormatL automatically grows the buffer sl@0: User::InfoPrint(message); sl@0: @endcode sl@0: sl@0: It is important to note that LString8 only supports automatic growth sl@0: when being manipulated directly as an LString8. When an LString8 is sl@0: passed to a function accepting a TDes8, that function will operate on sl@0: it as if it is a fixed-max-length descriptor. In that case, adequate sl@0: capacity must be reserved within the LString8 prior to calling the sl@0: function. This can either be achieved using the appropriate constructor or ReserveFreeCapacityL(). sl@0: sl@0: @code sl@0: extern void GetLastQuery(TDes8& aQuery); sl@0: extern void GetLastAuxQuery(TDes8& aQuery); sl@0: sl@0: LString8 query(KMaxQuerySize); // Guarantees query.MaxLength() >= KMaxQuerySize sl@0: GetLastQuery(query); sl@0: sl@0: // ... sl@0: sl@0: previousQueryMaxLength = query.MaxLength(); sl@0: sl@0: query.ReserveFreeCapacityL(KExtraRequiredSize); // Guarantees query.MaxLength() >= KExtraRequiredSize + previousQueryMaxLength; sl@0: GetLastAuxQuery(query); sl@0: sl@0: @endcode sl@0: sl@0: @par Relationship with TDes and RBuf sl@0: sl@0: LString8 derives from RBuf8 in order to achieve maximum sl@0: interoperability with existing descriptor-accepting APIs. This sl@0: derivation forces some unusual API compromises, however, due to the sl@0: unique characteristics of LString8 compared to other descriptors. sl@0: sl@0: Some of the mutating methods on the base classes, TDes8 and RBuf8, sl@0: panic when called with insufficient buffer space. Sufficient space is sl@0: a precondition of these base classes which LString8 relaxes with sl@0: its capability to start with zero length. LString8 defines new sl@0: leaving variants of these methods with auto-growth behaviour sl@0: (e.g. AppendL), but at the same time inherits the original methods sl@0: (e.g. Append). This makes it too easy for developers to call the sl@0: wrong method inadvertently. In order to address this, the original sl@0: non-leaving methods have been made private in LString8. Developers sl@0: should use the leaving LString8 versions. sl@0: sl@0: Note that, if required for any reason, the non-leaving method variants sl@0: may be accessed by explicitly qualifying the method name to the sl@0: appropriate parent type. For example: aString.TDes::Append(...). When sl@0: working with an LString8 but doing so via a TDes& typed variable, all sl@0: TDes8 APIs are directly available. sl@0: sl@0: Hiding these methods does not remove the problem entirely. The same sl@0: problem can happen if an LString object of insufficient size in passed sl@0: into a any API accepting a TDes. The advice is that developers always sl@0: ensure there is sufficient space before passing LString as a TDes. sl@0: sl@0: @par Performance Concerns sl@0: sl@0: While being simpler to use than existing descriptors in many cases, sl@0: LString8's use of heap allocation and its resizing variant methods sl@0: clearly come with associated costs. Their use in performance-critical sl@0: code should be carefully considered. On the other hand, LString8's sl@0: small stack footprint and ability to better-handle inputs of sl@0: unpredictable size may make them a better choice when the alternative sl@0: is a large, fixed-max-size TBuf or HBufC. sl@0: sl@0: @par Buffer Ownership sl@0: sl@0: Typically an LString8 will automatically allocate its own buffer, but sl@0: like RBuf8 it can also take ownership of a pre-existing raw memory sl@0: buffer or heap descriptor. sl@0: sl@0: The class is intended for instantiation. sl@0: sl@0: @see RBuf8 sl@0: @see TBuf8 sl@0: @see TPtr8 sl@0: @see HBufC8 sl@0: @see TDesC8 sl@0: @see TDes8 sl@0: @see LString sl@0: sl@0: */ sl@0: class LString8 : public RBuf8 sl@0: { sl@0: public: sl@0: /* sl@0: * We add leaving (auto-resizing) variants of the standard TDes sl@0: * methods where appropriate, and enhance the behaviour of the sl@0: * corresponding operators to match sl@0: */ sl@0: sl@0: LSTRING_CONSTRUCTORS_MAY_LEAVE sl@0: sl@0: IMPORT_C LString8(); sl@0: IMPORT_C ~LString8(); sl@0: sl@0: // Construct with initial capacity sl@0: IMPORT_C explicit LString8(TInt aInitialCapacity); sl@0: sl@0: // Construct by data copying sl@0: IMPORT_C LString8(const TDesC8& aDes); sl@0: IMPORT_C LString8(const TUint8* aZeroTerminatedString); sl@0: IMPORT_C LString8(const LString8& aDes); sl@0: sl@0: // Construction thru transfer of ownership sl@0: IMPORT_C explicit LString8(HBufC8* aHBuf); sl@0: IMPORT_C explicit LString8(TUint8 *aHeapCell,TInt aMaxLength); sl@0: IMPORT_C explicit LString8(TUint8 *aHeapCell,TInt aLength,TInt aMaxLength); sl@0: sl@0: // Assignment thru payload copying sl@0: IMPORT_C LString8& operator=(const TDesC8& aDes); sl@0: IMPORT_C LString8& operator=(const LString8& aDes); sl@0: IMPORT_C LString8& operator=(const TUint8* aZeroTerminatedString); sl@0: sl@0: // Assignment by transfer of payload to this object; sl@0: // supplied object is destroyed or zeroed. sl@0: IMPORT_C LString8& operator=(HBufC8* aHBuf); sl@0: sl@0: // Assign by transfer of payload ownership to this object; sl@0: // supplied object is destroyed or zeroed. sl@0: IMPORT_C void Assign(const LString8& aString); sl@0: IMPORT_C void Assign(const RBuf8& aRBuf); sl@0: IMPORT_C void Assign(HBufC8* aHBuf); sl@0: IMPORT_C void Assign(TUint8 *aHeapCell,TInt aMaxLength); sl@0: IMPORT_C void Assign(TUint8 *aHeapCell,TInt aLength,TInt aMaxLength); sl@0: sl@0: IMPORT_C void CreateL(RReadStream& aStream,TInt aMaxLength); sl@0: sl@0: IMPORT_C LString8& operator+=(TChar aChar); sl@0: IMPORT_C LString8& operator+=(const TDesC8 &aDes); sl@0: sl@0: IMPORT_C void CopyL(const TDesC8 &aDes); sl@0: IMPORT_C void CopyL(const TDesC16 &aDes); sl@0: IMPORT_C void CopyL(const TUint8 *aZeroTerminatedString); sl@0: IMPORT_C void CopyL(const TUint8 *aBuf,TInt aLength); sl@0: sl@0: IMPORT_C void SetLengthL(TInt aLength); sl@0: IMPORT_C void SetMaxLengthL(TInt aMaxLength); sl@0: IMPORT_C void Compress(); // deprecated; to be removed sl@0: IMPORT_C void ReserveFreeCapacityL(TInt aExtraSpaceLength); sl@0: IMPORT_C void Reset(); sl@0: sl@0: IMPORT_C void AppendL(TChar aChar); sl@0: IMPORT_C void AppendL(const TDesC8 &aDes); sl@0: IMPORT_C void AppendL(const TUint8 *aBuf,TInt aLength); sl@0: sl@0: IMPORT_C void FillL(TChar aChar,TInt aLength); sl@0: IMPORT_C void FillZL(TInt aLength); sl@0: sl@0: IMPORT_C void NumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth); sl@0: IMPORT_C void AppendNumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth); sl@0: IMPORT_C const TUint8 *PtrZL(); sl@0: IMPORT_C void CopyFL(const TDesC8 &aDes); sl@0: IMPORT_C void CopyCL(const TDesC8 &aDes); sl@0: IMPORT_C void CopyLCL(const TDesC8 &aDes); sl@0: IMPORT_C void CopyUCL(const TDesC8 &aDes); sl@0: IMPORT_C void CopyCPL(const TDesC8 &aDes); sl@0: IMPORT_C void AppendFillL(TChar aChar,TInt aLength); sl@0: IMPORT_C void ZeroTerminateL(); sl@0: IMPORT_C void SwapL(TDes8 &aDes); sl@0: IMPORT_C void SwapL(LString8 &aDes); // Added overload sl@0: IMPORT_C void InsertL(TInt aPos,const TDesC8 &aDes); sl@0: IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const TDesC8 &aDes); sl@0: IMPORT_C void JustifyL(const TDesC8 &aDes,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: IMPORT_C void NumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth); sl@0: IMPORT_C void NumUCL(TUint64 aVal, TRadix aRadix=EDecimal); sl@0: IMPORT_C TInt NumL(TReal aVal,const TRealFormat &aFormat) __SOFTFP; sl@0: IMPORT_C void NumL(TInt64 aVal); sl@0: IMPORT_C void NumL(TUint64 aVal, TRadix aRadix); sl@0: IMPORT_C void FormatL(TRefByValue aFmt,...); sl@0: IMPORT_C void FormatListL(const TDesC8 &aFmt,VA_LIST aList); sl@0: IMPORT_C void AppendJustifyL(const TDesC8 &Des,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: IMPORT_C void AppendJustifyL(const TDesC8 &Des,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: IMPORT_C void AppendJustifyL(const TUint8 *aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: IMPORT_C void AppendJustifyL(const TUint8 *aString,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: IMPORT_C void AppendNumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth); sl@0: IMPORT_C void AppendNumUCL(TUint64 aVal, TRadix aRadix=EDecimal); sl@0: IMPORT_C TInt AppendNumL(TReal aVal,const TRealFormat &aFormat) __SOFTFP; sl@0: IMPORT_C void AppendNumL(TInt64 aVal); sl@0: IMPORT_C void AppendNumL(TUint64 aVal, TRadix aRadix); sl@0: IMPORT_C void AppendFormatL(TRefByValue aFmt,...); sl@0: IMPORT_C void AppendFormatListL(const TDesC8 &aFmt,VA_LIST aList); sl@0: sl@0: using RBuf8::operator==; sl@0: IMPORT_C TBool operator==( const TUint8* aZeroTerminatedString) const; sl@0: using RBuf8::operator<; sl@0: IMPORT_C TBool operator<( const TUint8* aZeroTerminatedString) const; sl@0: using RBuf8::operator<=; sl@0: IMPORT_C TBool operator<=( const TUint8* aZeroTerminatedString) const; sl@0: using RBuf8::operator>; sl@0: IMPORT_C TBool operator>( const TUint8* aZeroTerminatedString) const; sl@0: using RBuf8::operator>=; sl@0: IMPORT_C TBool operator>=( const TUint8* aZeroTerminatedString) const; sl@0: using RBuf8::operator!=; sl@0: IMPORT_C TBool operator!=( const TUint8* aZeroTerminatedString) const; sl@0: using RBuf8::Compare; sl@0: IMPORT_C TInt Compare(const TUint8* aZeroTerminatedString) const; sl@0: using RBuf8::CompareF; sl@0: IMPORT_C TInt CompareF(const TUint8* aZeroTerminatedString) const; sl@0: using RBuf8::Match; sl@0: IMPORT_C TInt Match(const TUint8* aZeroTerminatedString) const; sl@0: using RBuf8::MatchF; sl@0: IMPORT_C TInt MatchF(const TUint8* aZeroTerminatedString) const; sl@0: using RBuf8::Find; sl@0: IMPORT_C TInt Find(const TUint8* aZeroTerminatedString) const; sl@0: using RBuf8::FindF; sl@0: IMPORT_C TInt FindF(const TUint8* aZeroTerminatedString) const; sl@0: sl@0: IMPORT_C void CopyFL(const TUint8* aZeroTerminatedString); sl@0: IMPORT_C void CopyLCL(const TUint8* aZeroTerminatedString); sl@0: IMPORT_C void CopyUCL(const TUint8* aZeroTerminatedString); sl@0: IMPORT_C void CopyCPL(const TUint8* aZeroTerminatedString); sl@0: IMPORT_C void InsertL(TInt aPos,const TUint8* aZeroTerminatedString); sl@0: IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const TUint8* aZeroTerminatedString); sl@0: IMPORT_C void JustifyL(const TUint8* aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: IMPORT_C void AppendL(const TUint8* aZeroTerminatedString); sl@0: IMPORT_C LString8& operator+=(const TUint8* aZeroTerminatedString); sl@0: sl@0: IMPORT_C LString8(const char* aCharStr); sl@0: sl@0: IMPORT_C TBool operator==( const char* aCharStr) const; sl@0: IMPORT_C TBool operator<( const char* aCharStr) const; sl@0: IMPORT_C TBool operator<=( const char* aCharStr) const; sl@0: IMPORT_C TBool operator>( const char* aCharStr) const; sl@0: IMPORT_C TBool operator>=( const char* aCharStr) const; sl@0: IMPORT_C TBool operator!=( const char* aCharStr) const; sl@0: IMPORT_C TInt Compare(const char* aCharStr) const; sl@0: IMPORT_C TInt CompareF(const char* aCharStr) const; sl@0: IMPORT_C TInt Match(const char* aCharStr) const; sl@0: IMPORT_C TInt MatchF(const char* aCharStr) const; sl@0: IMPORT_C TInt Find(const char* aCharStr) const; sl@0: IMPORT_C TInt Find(const char* aCharStr,TInt aLenS ) const; sl@0: IMPORT_C TInt FindF(const char* aCharStr) const; sl@0: IMPORT_C TInt FindF(const char* aCharStr,TInt aLenS) const; sl@0: sl@0: IMPORT_C LString8& operator=(const char* aCharStr); sl@0: IMPORT_C LString8& operator+=(const char* aCharStr); sl@0: IMPORT_C void CopyL(const char* aCharStr); sl@0: IMPORT_C void CopyFL(const char* aCharStr); sl@0: IMPORT_C void CopyLCL(const char* aCharStr); sl@0: IMPORT_C void CopyUCL(const char* aCharStr); sl@0: IMPORT_C void CopyCPL(const char* aCharStr); sl@0: IMPORT_C void InsertL(TInt aPos,const char* aCharStr); sl@0: IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const char* aCharStr); sl@0: IMPORT_C void AppendL(const char* aCharStr, TInt aLength); sl@0: IMPORT_C void AppendL(const char *aCharStr ); sl@0: IMPORT_C void JustifyL(const char* aCharStr,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: IMPORT_C void AppendJustifyL(const char* aCharStr,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: IMPORT_C void AppendJustifyL(const char* aCharStr,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: sl@0: protected: sl@0: sl@0: private: sl@0: /* sl@0: * capacity management methods sl@0: */ sl@0: void ReserveL(TInt aMinRequiredCapacity); sl@0: void ReserveCapacityGrowExponentialL(TInt aRequiredCapacity); sl@0: void ReserveCapacityGrowExponentialL(); sl@0: void ReserveFreeCapacityGrowExponentialL(TInt aRequiredEmptySpace); sl@0: sl@0: sl@0: //---------------------------------------------------------- sl@0: // These mutable TDes8 methods panic when called with an insufficient sl@0: // buffer space. sl@0: // A precondition for TDes8 use is that a sufficient sl@0: // sufficient buffer is allocated before making calls that write to the sl@0: // buffer. LString invalidates this precondition. sl@0: // LString inheriting these TDes methods makes it easy sl@0: // for developers to call them inadvertently. They have been made sl@0: // private to ensure the misunderstanding never happens. Developers should sl@0: // use the leaving (L suffixed) LString equivalents. sl@0: void SetLength(TInt aLength); sl@0: void SetMax(); sl@0: void Copy(const TDesC8 &aDes); sl@0: void Copy(const TDesC16 &aDes); sl@0: void Copy(const TUint8 *aBuf,TInt aLength); sl@0: void Copy(const TUint8 *aString); sl@0: void Append(TChar aChar); sl@0: void Append(const TDesC8 &aDes); sl@0: void Append(const TUint8 *aBuf,TInt aLength); sl@0: void Fill(TChar aChar,TInt aLength); sl@0: void FillZ(TInt aLength); sl@0: void NumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth); sl@0: void AppendNumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth); sl@0: const TUint8 *PtrZ(); sl@0: void CopyF(const TDesC8 &aDes); sl@0: void CopyC(const TDesC8 &aDes); sl@0: void CopyLC(const TDesC8 &aDes); sl@0: void CopyUC(const TDesC8 &aDes); sl@0: void CopyCP(const TDesC8 &aDes); sl@0: void AppendFill(TChar aChar,TInt aLength); sl@0: void ZeroTerminate(); sl@0: void Swap(TDes8 &aDes); sl@0: void Insert(TInt aPos,const TDesC8 &aDes); sl@0: void Replace(TInt aPos,TInt aLength,const TDesC8 &aDes); sl@0: void Justify(const TDesC8 &aDes,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: void NumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth); sl@0: void NumUC(TUint64 aVal, TRadix aRadix=EDecimal); sl@0: TInt Num(TReal aVal,const TRealFormat &aFormat) __SOFTFP; sl@0: void Num(TInt64 aVal); sl@0: void Num(TUint64 aVal, TRadix aRadix); sl@0: void Format(TRefByValue aFmt,...); sl@0: void FormatList(const TDesC8 &aFmt,VA_LIST aList); sl@0: void AppendJustify(const TDesC8 &Des,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: void AppendJustify(const TDesC8 &Des,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: void AppendJustify(const TUint8 *aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: void AppendJustify(const TUint8 *aZeroTerminatedString,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: void AppendNumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth); sl@0: void AppendNumUC(TUint64 aVal, TRadix aRadix=EDecimal); sl@0: TInt AppendNum(TReal aVal,const TRealFormat &aFormat) __SOFTFP; sl@0: void AppendNum(TInt64 aVal); sl@0: void AppendNum(TUint64 aVal, TRadix aRadix); sl@0: void AppendFormat(TRefByValue aFmt,TDes8Overflow *aOverflowHandler,...); sl@0: void AppendFormat(TRefByValue aFmt,...); sl@0: void AppendFormatList(const TDesC8 &aFmt,VA_LIST aList,TDes8Overflow *aOverflowHandler=NULL); sl@0: // end of TDes8 methods sl@0: //--------------------------------------------------- sl@0: sl@0: //---------------------------------------------------------- sl@0: // These mutable RBuf8 methods have been privatised because sl@0: // they make assumptions which are incompatible with the sl@0: // general use pattern of LString16. sl@0: void Swap(RBuf8& aRBuf); sl@0: TInt Create(TInt aMaxLength); sl@0: void CreateL(TInt aMaxLength); sl@0: TInt CreateMax(TInt aMaxLength); sl@0: void CreateMaxL(TInt aMaxLength); sl@0: TInt Create(const TDesC8& aDes); sl@0: void CreateL(const TDesC8& aDes); sl@0: TInt Create(const TDesC8& aDes,TInt aMaxLength); sl@0: void CreateL(const TDesC8& aDes,TInt aMaxLength); sl@0: void Close(); sl@0: void CleanupClosePushL(); sl@0: // end of privated RBuf16 methods sl@0: //--------------------------------------------------- sl@0: sl@0: void EnsureCapacityIncrementL(TInt aLengthIncrement); sl@0: void IncreaseCapacityL(); sl@0: sl@0: private: sl@0: //reserved data member for future-proofing sl@0: TInt iReserved; sl@0: }; sl@0: sl@0: /** sl@0: This is the 16-bit version of LString8. All the comments on LString8 apply equally. sl@0: sl@0: @see LString8 sl@0: @see RBuf16 sl@0: @see TBuf16 sl@0: @see TPtr16 sl@0: @see HBufC16 sl@0: @see TDesC16 sl@0: @see TDes16 sl@0: @see LString sl@0: */ sl@0: class LString16 : public RBuf16 sl@0: { sl@0: public: sl@0: /* sl@0: * We add leaving (auto-resizing) variants of the standard TDes sl@0: * methods where appropriate, and enhance the behaviour of the sl@0: * corresponding operators to match sl@0: */ sl@0: sl@0: LSTRING_CONSTRUCTORS_MAY_LEAVE sl@0: sl@0: IMPORT_C LString16(); sl@0: IMPORT_C ~LString16(); sl@0: sl@0: // Construct with initial capacity sl@0: IMPORT_C explicit LString16(TInt aInitialCapacity); sl@0: sl@0: // Construct by data copying sl@0: IMPORT_C LString16(const TDesC16& aDes); sl@0: IMPORT_C LString16(const TUint16* aZeroTerminatedString); sl@0: IMPORT_C LString16(const LString16& aDes); sl@0: sl@0: // Construction thru transfer of ownership sl@0: IMPORT_C explicit LString16(HBufC16* aHBuf); sl@0: IMPORT_C explicit LString16(TUint16 *aHeapCell,TInt aMaxLength); sl@0: IMPORT_C explicit LString16(TUint16 *aHeapCell,TInt aLength,TInt aMaxLength); sl@0: sl@0: // Assignment thru payload copying sl@0: IMPORT_C LString16& operator=(const TDesC16& aDes); sl@0: IMPORT_C LString16& operator=(const LString16& aDes); sl@0: IMPORT_C LString16& operator=(const TUint16* aZeroTerminatedString); sl@0: sl@0: // Assignment by transfer of payload to this object; sl@0: // supplied object is destroyed or zeroed. sl@0: IMPORT_C LString16& operator=(HBufC16* aHBuf); sl@0: sl@0: // Assign by transfer of payload ownership to this object; sl@0: // supplied object is destroyed or zeroed. sl@0: IMPORT_C void Assign(const LString16& aString); sl@0: IMPORT_C void Assign(const RBuf16& aRBuf); sl@0: IMPORT_C void Assign(HBufC16* aHBuf); sl@0: IMPORT_C void Assign(TUint16 *aHeapCell,TInt aMaxLength); sl@0: IMPORT_C void Assign(TUint16 *aHeapCell,TInt aLength,TInt aMaxLength); sl@0: sl@0: IMPORT_C void CreateL(RReadStream& aStream,TInt aMaxLength); sl@0: sl@0: IMPORT_C LString16& operator+=(TChar aChar); sl@0: IMPORT_C LString16& operator+=(const TDesC16 &aDes); sl@0: sl@0: IMPORT_C void CopyL(const TDesC16 &aDes); sl@0: IMPORT_C void CopyL(const TUint16 *aZeroTerminatedString); sl@0: IMPORT_C void CopyL(const TDesC8 &aDes); sl@0: IMPORT_C void CopyL(const TUint16 *aBuf,TInt aLength); sl@0: sl@0: IMPORT_C void SetLengthL(TInt aLength); sl@0: IMPORT_C void SetMaxLengthL(TInt aMaxLength); sl@0: IMPORT_C void Compress(); // deprecated; to be removed sl@0: IMPORT_C void ReserveFreeCapacityL(TInt aExtraSpaceLength); sl@0: IMPORT_C void Reset(); sl@0: sl@0: IMPORT_C void AppendL(TChar aChar); sl@0: IMPORT_C void AppendL(const TDesC16 &aDes); sl@0: IMPORT_C void AppendL(const TUint16 *aBuf,TInt aLength); sl@0: sl@0: IMPORT_C void FillL(TChar aChar,TInt aLength); sl@0: IMPORT_C void FillZL(TInt aLength); sl@0: sl@0: IMPORT_C void NumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth); sl@0: IMPORT_C void AppendNumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth); sl@0: IMPORT_C const TUint16 *PtrZL(); sl@0: IMPORT_C void CopyFL(const TDesC16 &aDes); sl@0: IMPORT_C void CopyCL(const TDesC16 &aDes); sl@0: IMPORT_C void CopyLCL(const TDesC16 &aDes); sl@0: IMPORT_C void CopyUCL(const TDesC16 &aDes); sl@0: IMPORT_C void CopyCPL(const TDesC16 &aDes); sl@0: IMPORT_C void AppendFillL(TChar aChar,TInt aLength); sl@0: IMPORT_C void ZeroTerminateL(); sl@0: IMPORT_C void SwapL(TDes16 &aDes); sl@0: IMPORT_C void SwapL(LString16 &aDes); // Added overload sl@0: IMPORT_C void InsertL(TInt aPos,const TDesC16 &aDes); sl@0: IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const TDesC16 &aDes); sl@0: IMPORT_C void JustifyL(const TDesC16 &aDes,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: IMPORT_C void NumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth); sl@0: IMPORT_C void NumUCL(TUint64 aVal, TRadix aRadix=EDecimal); sl@0: IMPORT_C TInt NumL(TReal aVal,const TRealFormat &aFormat) __SOFTFP; sl@0: IMPORT_C void NumL(TInt64 aVal); sl@0: IMPORT_C void NumL(TUint64 aVal, TRadix aRadix); sl@0: IMPORT_C void FormatL(TRefByValue aFmt,...); sl@0: IMPORT_C void FormatListL(const TDesC16 &aFmt,VA_LIST aList); sl@0: IMPORT_C void AppendJustifyL(const TDesC16 &Des,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: IMPORT_C void AppendJustifyL(const TDesC16 &Des,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: IMPORT_C void AppendJustifyL(const TUint16 *aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: IMPORT_C void AppendJustifyL(const TUint16 *aString,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: IMPORT_C void AppendNumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth); sl@0: IMPORT_C void AppendNumUCL(TUint64 aVal, TRadix aRadix=EDecimal); sl@0: IMPORT_C TInt AppendNumL(TReal aVal,const TRealFormat &aFormat) __SOFTFP; sl@0: IMPORT_C void AppendNumL(TInt64 aVal); sl@0: IMPORT_C void AppendNumL(TUint64 aVal, TRadix aRadix); sl@0: IMPORT_C void AppendFormatL(TRefByValue aFmt,...); sl@0: IMPORT_C void AppendFormatListL(const TDesC16 &aFmt,VA_LIST aList); sl@0: sl@0: using RBuf16::operator==; sl@0: IMPORT_C TBool operator==( const TUint16* aZeroTerminatedString) const; sl@0: using RBuf16::operator<; sl@0: IMPORT_C TBool operator<( const TUint16* aZeroTerminatedString) const; sl@0: using RBuf16::operator<=; sl@0: IMPORT_C TBool operator<=( const TUint16* aZeroTerminatedString) const; sl@0: using RBuf16::operator>; sl@0: IMPORT_C TBool operator>( const TUint16* aZeroTerminatedString) const; sl@0: using RBuf16::operator>=; sl@0: IMPORT_C TBool operator>=( const TUint16* aZeroTerminatedString) const; sl@0: using RBuf16::operator!=; sl@0: IMPORT_C TBool operator!=( const TUint16* aZeroTerminatedString) const; sl@0: using RBuf16::Compare; sl@0: IMPORT_C TInt Compare(const TUint16* aZeroTerminatedString) const; sl@0: using RBuf16::CompareF; sl@0: IMPORT_C TInt CompareF(const TUint16* aZeroTerminatedString) const; sl@0: using RBuf16::Match; sl@0: IMPORT_C TInt Match(const TUint16* aZeroTerminatedString) const; sl@0: using RBuf16::MatchF; sl@0: IMPORT_C TInt MatchF(const TUint16* aZeroTerminatedString) const; sl@0: using RBuf16::Find; sl@0: IMPORT_C TInt Find(const TUint16* aZeroTerminatedString) const; sl@0: using RBuf16::FindF; sl@0: IMPORT_C TInt FindF(const TUint16* aZeroTerminatedString) const; sl@0: sl@0: IMPORT_C void CopyFL(const TUint16* aZeroTerminatedString); sl@0: IMPORT_C void CopyLCL(const TUint16* aZeroTerminatedString); sl@0: IMPORT_C void CopyUCL(const TUint16* aZeroTerminatedString); sl@0: IMPORT_C void CopyCPL(const TUint16* aZeroTerminatedString); sl@0: IMPORT_C void InsertL(TInt aPos,const TUint16* aZeroTerminatedString); sl@0: IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const TUint16* aZeroTerminatedString); sl@0: IMPORT_C void JustifyL(const TUint16* aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: IMPORT_C void AppendL(const TUint16* aZeroTerminatedString); sl@0: IMPORT_C LString16& operator+=(const TUint16* aZeroTerminatedString); sl@0: sl@0: #ifdef NATIVE_WCHAR sl@0: IMPORT_C LString16(const wchar_t* aWideCharStr); sl@0: sl@0: IMPORT_C TBool operator==( const wchar_t* aWideCharStr) const; sl@0: IMPORT_C TBool operator<( const wchar_t* aWideCharStr) const; sl@0: IMPORT_C TBool operator<=( const wchar_t* aWideCharStr) const; sl@0: IMPORT_C TBool operator>( const wchar_t* aWideCharStr) const; sl@0: IMPORT_C TBool operator>=( const wchar_t* aWideCharStr) const; sl@0: IMPORT_C TBool operator!=( const wchar_t* aWideCharStr) const; sl@0: IMPORT_C TInt Compare(const wchar_t* aWideCharStr) const; sl@0: IMPORT_C TInt CompareF(const wchar_t* aWideCharStr) const; sl@0: IMPORT_C TInt Match(const wchar_t* aWideCharStr) const; sl@0: IMPORT_C TInt MatchF(const wchar_t* aWideCharStr) const; sl@0: IMPORT_C TInt Find(const wchar_t* aWideCharStr) const; sl@0: IMPORT_C TInt Find(const wchar_t* aWideCharStr,TInt aLenS ) const; sl@0: IMPORT_C TInt FindF(const wchar_t* aWideCharStr) const; sl@0: IMPORT_C TInt FindF(const wchar_t* aWideCharStr,TInt aLenS) const; sl@0: sl@0: IMPORT_C LString16& operator=(const wchar_t* aWideCharStr); sl@0: IMPORT_C LString16& operator+=(const wchar_t* aWideCharStr); sl@0: IMPORT_C void CopyL(const wchar_t* aWideCharStr); sl@0: IMPORT_C void CopyFL(const wchar_t* aWideCharStr); sl@0: IMPORT_C void CopyLCL(const wchar_t* aWideCharStr); sl@0: IMPORT_C void CopyUCL(const wchar_t* aWideCharStr); sl@0: IMPORT_C void CopyCPL(const wchar_t* aWideCharStr); sl@0: IMPORT_C void InsertL(TInt aPos,const wchar_t* aWideCharStr); sl@0: IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const wchar_t* aWideCharStr); sl@0: IMPORT_C void AppendL(const wchar_t* aWideCharStr, TInt aLength); sl@0: IMPORT_C void AppendL(const wchar_t* aWideCharStr); sl@0: IMPORT_C void JustifyL(const wchar_t* aWideCharStr,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: IMPORT_C void AppendJustifyL(const wchar_t* aWideCharStr,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: IMPORT_C void AppendJustifyL(const wchar_t* aWideCharStr,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: sl@0: #endif// NATIVE_WCHAR sl@0: sl@0: sl@0: protected: sl@0: sl@0: private: sl@0: /* sl@0: * New capacity management API sl@0: */ sl@0: void ReserveL(TInt aMinRequiredCapacity); sl@0: void ReserveCapacityGrowExponentialL(TInt aRequiredCapacity); sl@0: void ReserveCapacityGrowExponentialL(); sl@0: void ReserveFreeCapacityGrowExponentialL(TInt aRequiredEmptySpace); sl@0: sl@0: sl@0: //---------------------------------------------------------- sl@0: // These mutable TDes16 methods panic when called with an insufficient sl@0: // buffer space. sl@0: // A precondition for TDes16 use is that a sufficient sl@0: // sufficient buffer is allocated before making calls that write to the sl@0: // buffer. LString invalidates this precondition. sl@0: // LString inheriting these TDes methods makes it easy sl@0: // for developers to call them inadvertently. They have been made sl@0: // private to ensure the misunderstanding never happens. Developers should sl@0: // use the leaving (L suffixed) LString equivalents. sl@0: void SetLength(TInt aLength); sl@0: void SetMax(); sl@0: void Copy(const TDesC8 &aDes); sl@0: void Copy(const TDesC16 &aDes); sl@0: void Copy(const TUint16 *aBuf,TInt aLength); sl@0: void Copy(const TUint16 *aString); sl@0: void Append(TChar aChar); sl@0: void Append(const TDesC16 &aDes); sl@0: void Append(const TUint16 *aBuf,TInt aLength); sl@0: void Fill(TChar aChar,TInt aLength); sl@0: void FillZ(TInt aLength); sl@0: void NumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth); sl@0: void AppendNumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth); sl@0: const TUint16 *PtrZ(); sl@0: void CopyF(const TDesC16 &aDes); sl@0: void CopyC(const TDesC16 &aDes); sl@0: void CopyLC(const TDesC16 &aDes); sl@0: void CopyUC(const TDesC16 &aDes); sl@0: void CopyCP(const TDesC16 &aDes); sl@0: void AppendFill(TChar aChar,TInt aLength); sl@0: void ZeroTerminate(); sl@0: void Swap(TDes16 &aDes); sl@0: void Insert(TInt aPos,const TDesC16 &aDes); sl@0: void Replace(TInt aPos,TInt aLength,const TDesC16 &aDes); sl@0: void Justify(const TDesC16 &aDes,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: void NumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth); sl@0: void NumUC(TUint64 aVal, TRadix aRadix=EDecimal); sl@0: TInt Num(TReal aVal,const TRealFormat &aFormat) __SOFTFP; sl@0: void Num(TInt64 aVal); sl@0: void Num(TUint64 aVal, TRadix aRadix); sl@0: void Format(TRefByValue aFmt,...); sl@0: void FormatList(const TDesC16 &aFmt,VA_LIST aList); sl@0: void AppendJustify(const TDesC16 &Des,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: void AppendJustify(const TDesC16 &Des,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: void AppendJustify(const TUint16 *aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: void AppendJustify(const TUint16 *aZeroTerminatedString,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill); sl@0: void AppendNumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth); sl@0: void AppendNumUC(TUint64 aVal, TRadix aRadix=EDecimal); sl@0: TInt AppendNum(TReal aVal,const TRealFormat &aFormat) __SOFTFP; sl@0: void AppendNum(TInt64 aVal); sl@0: void AppendNum(TUint64 aVal, TRadix aRadix); sl@0: void AppendFormat(TRefByValue aFmt,TDes16Overflow *aOverflowHandler,...); sl@0: void AppendFormat(TRefByValue aFmt,...); sl@0: void AppendFormatList(const TDesC16 &aFmt,VA_LIST aList,TDes16Overflow *aOverflowHandler=NULL); sl@0: // end of TDes16 methods sl@0: //--------------------------------------------------- sl@0: sl@0: //---------------------------------------------------------- sl@0: // These mutable RBuf16 methods have been privatised because sl@0: // they make assumptions which are incompatible with the sl@0: // general use pattern of LString16. sl@0: void Swap(RBuf16& aRBuf); sl@0: TInt Create(TInt aMaxLength); sl@0: void CreateL(TInt aMaxLength); sl@0: TInt CreateMax(TInt aMaxLength); sl@0: void CreateMaxL(TInt aMaxLength); sl@0: TInt Create(const TDesC16& aDes); sl@0: void CreateL(const TDesC16& aDes); sl@0: TInt Create(const TDesC16& aDes,TInt aMaxLength); sl@0: void CreateL(const TDesC16& aDes,TInt aMaxLength); sl@0: void Close(); sl@0: void CleanupClosePushL(); sl@0: // end of privated RBuf16 methods sl@0: //--------------------------------------------------- sl@0: sl@0: void EnsureCapacityIncrementL(TInt aLengthIncrement); sl@0: void IncreaseCapacityL(); sl@0: sl@0: private: sl@0: //reserved data member for future-proofing sl@0: TInt iReserved; sl@0: }; sl@0: sl@0: sl@0: /** sl@0: Type alias for LString16. sl@0: sl@0: LString is typically used in preference to LString16 when manipulating sl@0: Unicode text, in the same way that TDesC is typically used in sl@0: preference to TDesC16. sl@0: */ sl@0: typedef LString16 LString; sl@0: sl@0: /** sl@0: Type alias for LString8. sl@0: sl@0: LData can be used to better express intent when using an LString8 to sl@0: manipulate raw binary (non character) data. sl@0: */ sl@0: typedef LString8 LData; sl@0: sl@0: #undef LSTRING_CONSTRUCTORS_MAY_LEAVE sl@0: sl@0: #endif // !ESTRING_H