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