Symaptic: os/ossrv/lowlevellibsandfws/genericusabilitylib/inc/estring.h@260cb5ec6c19

     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 //

    16 #ifndef ESTRING_H

    17 #define ESTRING_H

    19 #include <e32std.h>

    21 // this macro is defined only if the target is WINSCW and wchar_t is ON

    22 // (i.e OPTION CW -wchar_t on)

    23 // and  if the target is any thing other than WINSCW

    24 // it is being assumed that wchar_t is ON(OPTION CW -wchar_t on by

    25 // default or other wise)

    26 #define NATIVE_WCHAR // most platforms do wchar_t properly

    27 #if defined __cplusplus && defined __WINSCW__

    28 #if !__option(wchar_type) // without the wchar_type option

    29 typedef unsigned short wchar_t; // needs a typedef

    30 #undef NATIVE_WCHAR // which is not native

    31 #endif

    32 #endif

    34 // Since the LStrings can leave in their constructors, we have to make

    35 // sure to avoid the operator new/delete ELeave mismatch problem that

    36 // can result in the top level LString object heap being

    37 // leaked. These operator delete overloads match the global operator

    38 // new overloads applicable to the LString classes (which are

    39 // non-CBase derived).

    40 //

    41 // Note that when allocating a native C++ array of LStrings, only the

    42 // default constructor is invoked which cannot leave. So there are no

    43 // issues related to the array case.

    45 #define LSTRING_CONSTRUCTORS_MAY_LEAVE \

    46 	static void operator delete(TAny* aPtr) __NO_THROW \

    47 		{ \

    48 		return ::operator delete(aPtr); \

    49 		} \

    50 	\

    51 	static void operator delete(TAny* aPtr, TLeave) __NO_THROW \

    52 		{ \

    53 		return ::operator delete(aPtr); \

    54 		} \

    55 	\

    56 	static void operator delete(TAny*, TAny*) __NO_THROW \

    57 		{ \

    58 		}

    60 /**

    61 	@file

    63 	A self-managing descriptor class

    65    	@publishedAll

    66    	@released

    67 */

    69 /**

    70 @class LString8

    72 LString8 is a convenient, general-purpose 8 bit string class derived

    73 from RBuf8. LString8 adds automatic cleanup and on-demand buffer

    74 resize facilities.

    76 @par L-Classes

    78 Note: The L prefix denotes that construction, copying, passing and

    79 returning by value, assignment, and manipulation via operators should

    80 all be considered potentially leaving operations unless otherwise

    81 explicitly documented. Code that uses LString8 should be written

    82 accordingly, in leave-safe style.

    84 @par Descriptor Relationships

    86 Like an RBuf8, an LString8 can be passed to any function that is

    87 prototyped to take a TDes8 or a TDesC8 reference. Again like an

    88 RBuf8, an LString8 maintains its string data in a heap buffer.

    90 @par Value-Type Behaviour

    92 Unlike RBuf8, an LString8 may be used much like a simple T class;

    93 LString8 typed variables will automatically clean up after themselves

    94 when they go out of scope, and LString8 typed fields will similarly

    95 automatically release all owned resources when their containing object

    96 is destroyed.

    98 For example, where:

   100 @code

   101 RBuf8 buf;

   102 buf.CleanupClosePushL();

   103 ...

   104 CleanupStack::PopAndDestroy();

   105 @endcode

   107 would be required, with LString8:

   109 @code

   110 LString8 buf;

   111 ...

   112 @endcode

   114 will suffice. Pushing an LString8 onto the cleanup stack is not

   115 necessary or recommended, but the effects of doing so are

   116 benign. LString8 instances can also be passed and returned by value,

   117 but note that doing so may trigger implicit heap allocation and cause

   118 a leave with KErrNoMemory.

   120 @code

   121 void TakeString(LString8 aString)

   122 	{

   123 	// ...

   124 	}

   126 LString8 ReturnString(LString8 aString)

   127 	{

   128 	TakeString(aString); // Statement may leave with KErrNoMemory

   129 	return aString; // Statement may leave with KErrNoMemory

   130 	}

   131 @endcode

   133 As with other descriptors, passing by reference when possible is more

   134 efficient.

   136 @par On-Demand Growth

   138 In addition to the value-type semantics described above, LString8

   139 also supports automatic in-place resizing. All standard descriptor

   140 methods are available, but for any non-leaving descriptor method that

   141 may panic due to buffer overflow, LString8 adds a corresponding

   142 leaving method that automatically expands the underlying buffer

   143 on-demand. For example, Append() will panic if the new data overflows

   144 available buffer space, while AppendL() will attempt to realloc the

   145 buffer as necessary. The new leaving variants may therefore leave with

   146 KErrNoMemory, may invalidate any existing raw pointers into the data

   147 buffer (e.g. those previously returned by Ptr()), and may change the

   148 value returned by MaxLength().

   150 @code

   151 LString8 message; // Zero length

   152 message.FormatL(_L("This is message %n from %S"), n, &s); // FormatL automatically grows the buffer

   153 User::InfoPrint(message);

   154 @endcode

   156 It is important to note that LString8 only supports automatic growth

   157 when being manipulated directly as an LString8. When an LString8 is

   158 passed to a function accepting a TDes8, that function will operate on

   159 it as if it is a fixed-max-length descriptor. In that case, adequate

   160 capacity must be reserved within the LString8 prior to calling the

   161 function. This can either be achieved using the appropriate constructor or ReserveFreeCapacityL().

   163 @code

   164 extern void GetLastQuery(TDes8& aQuery);

   165 extern void GetLastAuxQuery(TDes8& aQuery);

   167 LString8 query(KMaxQuerySize); // Guarantees query.MaxLength() >= KMaxQuerySize

   168 GetLastQuery(query);

   170 // ...

   172 previousQueryMaxLength = query.MaxLength();

   174 query.ReserveFreeCapacityL(KExtraRequiredSize); // Guarantees query.MaxLength() >= KExtraRequiredSize + previousQueryMaxLength;

   175 GetLastAuxQuery(query);

   177 @endcode

   179 @par Relationship with TDes and RBuf

   181 LString8 derives from RBuf8 in order to achieve maximum

   182 interoperability with existing descriptor-accepting APIs. This

   183 derivation forces some unusual API compromises, however, due to the

   184 unique characteristics of LString8 compared to other descriptors.

   186 Some of the mutating methods on the base classes, TDes8 and RBuf8,

   187 panic when called with insufficient buffer space.  Sufficient space is

   188 a precondition of these base classes which LString8 relaxes with

   189 its capability to start with zero length.  LString8 defines new

   190 leaving variants of these methods with auto-growth behaviour

   191 (e.g. AppendL), but at the same time inherits the original methods

   192 (e.g. Append).  This makes it too easy for developers to call the

   193 wrong method inadvertently. In order to address this, the original

   194 non-leaving methods have been made private in LString8. Developers

   195 should use the leaving LString8 versions.

   197 Note that, if required for any reason, the non-leaving method variants

   198 may be accessed by explicitly qualifying the method name to the

   199 appropriate parent type. For example: aString.TDes::Append(...). When

   200 working with an LString8 but doing so via a TDes& typed variable, all

   201 TDes8 APIs are directly available.

   203 Hiding these methods does not remove the problem entirely.  The same

   204 problem can happen if an LString object of insufficient size in passed

   205 into a any API accepting a TDes. The advice is that developers always

   206 ensure there is sufficient space before passing LString as a TDes.

   208 @par Performance Concerns

   210 While being simpler to use than existing descriptors in many cases,

   211 LString8's use of heap allocation and its resizing variant methods

   212 clearly come with associated costs. Their use in performance-critical

   213 code should be carefully considered. On the other hand, LString8's

   214 small stack footprint and ability to better-handle inputs of

   215 unpredictable size may make them a better choice when the alternative

   216 is a large, fixed-max-size TBuf or HBufC.

   218 @par Buffer Ownership

   220 Typically an LString8 will automatically allocate its own buffer, but

   221 like RBuf8 it can also take ownership of a pre-existing raw memory

   222 buffer or heap descriptor.

   224 The class is intended for instantiation.

   226 @see RBuf8

   227 @see TBuf8

   228 @see TPtr8

   229 @see HBufC8

   230 @see TDesC8

   231 @see TDes8

   232 @see LString

   234 */

   235 class LString8 : public RBuf8

   236 	{

   237 public:

   238 	/*

   239 	 * We add leaving (auto-resizing) variants of the standard TDes

   240 	 * methods where appropriate, and enhance the behaviour of the

   241 	 * corresponding operators to match

   242 	 */

   244 	LSTRING_CONSTRUCTORS_MAY_LEAVE

   246 	IMPORT_C LString8();

   247 	IMPORT_C ~LString8();

   249 	// Construct with initial capacity

   250 	IMPORT_C explicit LString8(TInt aInitialCapacity);

   252 	// Construct by data copying

   253 	IMPORT_C LString8(const TDesC8& aDes);

   254 	IMPORT_C LString8(const TUint8* aZeroTerminatedString);

   255 	IMPORT_C LString8(const LString8& aDes);

   257 	// Construction thru transfer of ownership

   258 	IMPORT_C explicit LString8(HBufC8* aHBuf);

   259 	IMPORT_C explicit LString8(TUint8 *aHeapCell,TInt aMaxLength);

   260 	IMPORT_C explicit LString8(TUint8 *aHeapCell,TInt aLength,TInt aMaxLength);

   262 	// Assignment thru payload copying

   263 	IMPORT_C LString8& operator=(const TDesC8& aDes);

   264 	IMPORT_C LString8& operator=(const LString8& aDes);

   265 	IMPORT_C LString8& operator=(const TUint8* aZeroTerminatedString);

   267 	// Assignment by transfer of payload to this object;

   268 	// supplied object is destroyed or zeroed.

   269 	IMPORT_C LString8& operator=(HBufC8* aHBuf);

   271 	// Assign by transfer of payload ownership to this object;

   272 	// supplied object is destroyed or zeroed.

   273 	IMPORT_C void Assign(const LString8& aString);

   274 	IMPORT_C void Assign(const RBuf8& aRBuf);

   275 	IMPORT_C void Assign(HBufC8* aHBuf);

   276 	IMPORT_C void Assign(TUint8 *aHeapCell,TInt aMaxLength);

   277 	IMPORT_C void Assign(TUint8 *aHeapCell,TInt aLength,TInt aMaxLength);

   279 	IMPORT_C void CreateL(RReadStream& aStream,TInt aMaxLength);

   281 	IMPORT_C LString8& operator+=(TChar aChar);

   282 	IMPORT_C LString8& operator+=(const TDesC8 &aDes);

   284 	IMPORT_C void CopyL(const TDesC8 &aDes);

   285 	IMPORT_C void CopyL(const TDesC16 &aDes);

   286 	IMPORT_C void CopyL(const TUint8 *aZeroTerminatedString);

   287 	IMPORT_C void CopyL(const TUint8 *aBuf,TInt aLength);

   289  	IMPORT_C void SetLengthL(TInt aLength);

   290  	IMPORT_C void SetMaxLengthL(TInt aMaxLength);

   291 	IMPORT_C void Compress(); // deprecated; to be removed

   292 	IMPORT_C void ReserveFreeCapacityL(TInt aExtraSpaceLength);

   293 	IMPORT_C void Reset();

   295 	IMPORT_C void AppendL(TChar aChar);

   296 	IMPORT_C void AppendL(const TDesC8 &aDes);

   297 	IMPORT_C void AppendL(const TUint8 *aBuf,TInt aLength);

   299 	IMPORT_C void FillL(TChar aChar,TInt aLength);

   300 	IMPORT_C void FillZL(TInt aLength);

   302 	IMPORT_C void NumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth);

   303 	IMPORT_C void AppendNumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth);

   304 	IMPORT_C const TUint8 *PtrZL();

   305 	IMPORT_C void CopyFL(const TDesC8 &aDes);

   306 	IMPORT_C void CopyCL(const TDesC8 &aDes);

   307 	IMPORT_C void CopyLCL(const TDesC8 &aDes);

   308 	IMPORT_C void CopyUCL(const TDesC8 &aDes);

   309 	IMPORT_C void CopyCPL(const TDesC8 &aDes);

   310 	IMPORT_C void AppendFillL(TChar aChar,TInt aLength);

   311 	IMPORT_C void ZeroTerminateL();

   312 	IMPORT_C void SwapL(TDes8 &aDes);

   313 	IMPORT_C void SwapL(LString8 &aDes); // Added overload

   314 	IMPORT_C void InsertL(TInt aPos,const TDesC8 &aDes);

   315 	IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const TDesC8 &aDes);

   316 	IMPORT_C void JustifyL(const TDesC8 &aDes,TInt aWidth,TAlign anAlignment,TChar aFill);

   317 	IMPORT_C void NumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth);

   318 	IMPORT_C void NumUCL(TUint64 aVal, TRadix aRadix=EDecimal);

   319 	IMPORT_C TInt NumL(TReal aVal,const TRealFormat &aFormat) __SOFTFP;

   320 	IMPORT_C void NumL(TInt64 aVal);

   321 	IMPORT_C void NumL(TUint64 aVal, TRadix aRadix);

   322 	IMPORT_C void FormatL(TRefByValue<const TDesC8> aFmt,...);

   323 	IMPORT_C void FormatListL(const TDesC8 &aFmt,VA_LIST aList);

   324 	IMPORT_C void AppendJustifyL(const TDesC8 &Des,TInt aWidth,TAlign anAlignment,TChar aFill);

   325 	IMPORT_C void AppendJustifyL(const TDesC8 &Des,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);

   326 	IMPORT_C void AppendJustifyL(const TUint8 *aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill);

   327 	IMPORT_C void AppendJustifyL(const TUint8 *aString,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);

   328 	IMPORT_C void AppendNumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth);

   329 	IMPORT_C void AppendNumUCL(TUint64 aVal, TRadix aRadix=EDecimal);

   330 	IMPORT_C TInt AppendNumL(TReal aVal,const TRealFormat &aFormat) __SOFTFP;

   331 	IMPORT_C void AppendNumL(TInt64 aVal);

   332 	IMPORT_C void AppendNumL(TUint64 aVal, TRadix aRadix);

   333 	IMPORT_C void AppendFormatL(TRefByValue<const TDesC8> aFmt,...);

   334 	IMPORT_C void AppendFormatListL(const TDesC8 &aFmt,VA_LIST aList);

   336 	using RBuf8::operator==;

   337 	IMPORT_C TBool operator==( const TUint8* aZeroTerminatedString) const;

   338 	using RBuf8::operator<;

   339 	IMPORT_C TBool operator<( const TUint8* aZeroTerminatedString) const;

   340 	using RBuf8::operator<=;

   341 	IMPORT_C TBool operator<=( const TUint8* aZeroTerminatedString) const;

   342 	using RBuf8::operator>;

   343 	IMPORT_C TBool operator>( const TUint8* aZeroTerminatedString) const;

   344 	using RBuf8::operator>=;

   345 	IMPORT_C TBool operator>=( const TUint8* aZeroTerminatedString) const;

   346 	using RBuf8::operator!=;

   347 	IMPORT_C TBool operator!=( const TUint8* aZeroTerminatedString) const;

   348 	using RBuf8::Compare;

   349 	IMPORT_C TInt Compare(const TUint8* aZeroTerminatedString) const;

   350 	using RBuf8::CompareF;

   351 	IMPORT_C TInt CompareF(const TUint8* aZeroTerminatedString) const;

   352 	using RBuf8::Match;

   353 	IMPORT_C TInt Match(const TUint8* aZeroTerminatedString) const;

   354 	using RBuf8::MatchF;

   355 	IMPORT_C TInt MatchF(const TUint8* aZeroTerminatedString) const;

   356 	using RBuf8::Find;

   357 	IMPORT_C TInt Find(const TUint8* aZeroTerminatedString) const;

   358 	using RBuf8::FindF;

   359 	IMPORT_C TInt FindF(const TUint8* aZeroTerminatedString) const;

   361 	IMPORT_C void CopyFL(const TUint8* aZeroTerminatedString);

   362 	IMPORT_C void CopyLCL(const TUint8* aZeroTerminatedString);

   363 	IMPORT_C void CopyUCL(const TUint8* aZeroTerminatedString);

   364 	IMPORT_C void CopyCPL(const TUint8* aZeroTerminatedString);

   365 	IMPORT_C void InsertL(TInt aPos,const TUint8* aZeroTerminatedString);

   366 	IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const TUint8* aZeroTerminatedString);

   367 	IMPORT_C void JustifyL(const TUint8* aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill);

   368 	IMPORT_C void AppendL(const TUint8* aZeroTerminatedString);

   369 	IMPORT_C LString8& operator+=(const TUint8* aZeroTerminatedString);

   371 	IMPORT_C LString8(const char* aCharStr);

   373 	IMPORT_C TBool operator==( const char* aCharStr) const;

   374 	IMPORT_C TBool operator<( const char* aCharStr) const;

   375 	IMPORT_C TBool operator<=( const char* aCharStr) const;

   376 	IMPORT_C TBool operator>( const char* aCharStr) const;

   377 	IMPORT_C TBool operator>=( const char* aCharStr) const;

   378 	IMPORT_C TBool operator!=( const char* aCharStr) const;

   379 	IMPORT_C TInt Compare(const char* aCharStr) const;

   380 	IMPORT_C TInt CompareF(const char* aCharStr) const;

   381 	IMPORT_C TInt Match(const char* aCharStr) const;

   382 	IMPORT_C TInt MatchF(const char* aCharStr) const;

   383 	IMPORT_C TInt Find(const char* aCharStr) const;

   384 	IMPORT_C TInt Find(const char* aCharStr,TInt aLenS ) const;

   385 	IMPORT_C TInt FindF(const char* aCharStr) const;

   386 	IMPORT_C TInt FindF(const char* aCharStr,TInt aLenS) const;

   388 	IMPORT_C LString8& operator=(const char* aCharStr);

   389 	IMPORT_C LString8& operator+=(const char* aCharStr);

   390 	IMPORT_C void CopyL(const char* aCharStr);

   391 	IMPORT_C void CopyFL(const char* aCharStr);

   392 	IMPORT_C void CopyLCL(const char* aCharStr);

   393 	IMPORT_C void CopyUCL(const char* aCharStr);

   394 	IMPORT_C void CopyCPL(const char* aCharStr);

   395 	IMPORT_C void InsertL(TInt aPos,const char* aCharStr);

   396 	IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const char* aCharStr);

   397 	IMPORT_C void AppendL(const char* aCharStr, TInt aLength);

   398 	IMPORT_C void AppendL(const char *aCharStr );

   399 	IMPORT_C void JustifyL(const char* aCharStr,TInt aWidth,TAlign anAlignment,TChar aFill);

   400 	IMPORT_C void AppendJustifyL(const char* aCharStr,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);

   401 	IMPORT_C void AppendJustifyL(const char* aCharStr,TInt aWidth,TAlign anAlignment,TChar aFill);

   403 protected:

   405 private:

   406 	/*

   407 	 * capacity management methods

   408 	 */

   409 	void ReserveL(TInt aMinRequiredCapacity);

   410 	void ReserveCapacityGrowExponentialL(TInt aRequiredCapacity);

   411 	void ReserveCapacityGrowExponentialL();

   412 	void ReserveFreeCapacityGrowExponentialL(TInt aRequiredEmptySpace);

   415 	//----------------------------------------------------------

   416 	// These mutable TDes8 methods panic when called with an insufficient

   417 	// buffer space.

   418 	// A precondition for TDes8 use is that a sufficient

   419 	// sufficient buffer is allocated before making calls that write to the

   420 	// buffer. LString invalidates this precondition.

   421 	// LString inheriting these TDes methods makes it easy

   422 	// for developers to call them inadvertently. They have been made

   423 	// private to ensure the misunderstanding never happens. Developers should

   424 	// use the leaving (L suffixed) LString equivalents.

   425 	void SetLength(TInt aLength);

   426 	void SetMax();

   427 	void Copy(const TDesC8 &aDes);

   428 	void Copy(const TDesC16 &aDes);

   429 	void Copy(const TUint8 *aBuf,TInt aLength);

   430 	void Copy(const TUint8 *aString);

   431 	void Append(TChar aChar);

   432 	void Append(const TDesC8 &aDes);

   433 	void Append(const TUint8 *aBuf,TInt aLength);

   434 	void Fill(TChar aChar,TInt aLength);

   435 	void FillZ(TInt aLength);

   436 	void NumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth);

   437 	void AppendNumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth);

   438 	const TUint8 *PtrZ();

   439 	void CopyF(const TDesC8 &aDes);

   440 	void CopyC(const TDesC8 &aDes);

   441 	void CopyLC(const TDesC8 &aDes);

   442 	void CopyUC(const TDesC8 &aDes);

   443 	void CopyCP(const TDesC8 &aDes);

   444 	void AppendFill(TChar aChar,TInt aLength);

   445 	void ZeroTerminate();

   446 	void Swap(TDes8 &aDes);

   447 	void Insert(TInt aPos,const TDesC8 &aDes);

   448 	void Replace(TInt aPos,TInt aLength,const TDesC8 &aDes);

   449 	void Justify(const TDesC8 &aDes,TInt aWidth,TAlign anAlignment,TChar aFill);

   450 	void NumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth);

   451 	void NumUC(TUint64 aVal, TRadix aRadix=EDecimal);

   452 	TInt Num(TReal aVal,const TRealFormat &aFormat) __SOFTFP;

   453 	void Num(TInt64 aVal);

   454 	void Num(TUint64 aVal, TRadix aRadix);

   455 	void Format(TRefByValue<const TDesC8> aFmt,...);

   456 	void FormatList(const TDesC8 &aFmt,VA_LIST aList);

   457 	void AppendJustify(const TDesC8 &Des,TInt aWidth,TAlign anAlignment,TChar aFill);

   458 	void AppendJustify(const TDesC8 &Des,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);

   459 	void AppendJustify(const TUint8 *aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill);

   460 	void AppendJustify(const TUint8 *aZeroTerminatedString,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);

   461 	void AppendNumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth);

   462 	void AppendNumUC(TUint64 aVal, TRadix aRadix=EDecimal);

   463 	TInt AppendNum(TReal aVal,const TRealFormat &aFormat) __SOFTFP;

   464 	void AppendNum(TInt64 aVal);

   465 	void AppendNum(TUint64 aVal, TRadix aRadix);

   466 	void AppendFormat(TRefByValue<const TDesC8> aFmt,TDes8Overflow *aOverflowHandler,...);

   467 	void AppendFormat(TRefByValue<const TDesC8> aFmt,...);

   468 	void AppendFormatList(const TDesC8 &aFmt,VA_LIST aList,TDes8Overflow *aOverflowHandler=NULL);

   469 	// end of TDes8 methods

   470 	//---------------------------------------------------

   472 	//----------------------------------------------------------

   473 	// These mutable RBuf8 methods have been privatised because

   474 	// they make assumptions which are incompatible with the

   475 	// general use pattern of LString16.

   476 	void Swap(RBuf8& aRBuf);

   477 	TInt Create(TInt aMaxLength);

   478 	void CreateL(TInt aMaxLength);

   479 	TInt CreateMax(TInt aMaxLength);

   480 	void CreateMaxL(TInt aMaxLength);

   481 	TInt Create(const TDesC8& aDes);

   482 	void CreateL(const TDesC8& aDes);

   483 	TInt Create(const TDesC8& aDes,TInt aMaxLength);

   484 	void CreateL(const TDesC8& aDes,TInt aMaxLength);

   485 	void Close();

   486 	void CleanupClosePushL();

   487 	// end of privated RBuf16 methods

   488 	//---------------------------------------------------

   490 	void EnsureCapacityIncrementL(TInt aLengthIncrement);

   491 	void IncreaseCapacityL();

   493 private:

   494 	//reserved data member for future-proofing

   495 	TInt iReserved;

   496 	};

   498 /**

   499 This is the 16-bit version of LString8. All the comments on LString8 apply equally.

   501 @see LString8

   502 @see RBuf16

   503 @see TBuf16

   504 @see TPtr16

   505 @see HBufC16

   506 @see TDesC16

   507 @see TDes16

   508 @see LString

   509 */

   510 class LString16 : public RBuf16

   511 	{

   512 public:

   513 	/*

   514 	 * We add leaving (auto-resizing) variants of the standard TDes

   515 	 * methods where appropriate, and enhance the behaviour of the

   516 	 * corresponding operators to match

   517 	 */

   519 	LSTRING_CONSTRUCTORS_MAY_LEAVE

   521 	IMPORT_C LString16();

   522 	IMPORT_C ~LString16();

   524 	// Construct with initial capacity

   525 	IMPORT_C explicit LString16(TInt aInitialCapacity);

   527 	// Construct by data copying

   528 	IMPORT_C LString16(const TDesC16& aDes);

   529 	IMPORT_C LString16(const TUint16* aZeroTerminatedString);

   530 	IMPORT_C LString16(const LString16& aDes);

   532 	// Construction thru transfer of ownership

   533 	IMPORT_C explicit LString16(HBufC16* aHBuf);

   534 	IMPORT_C explicit LString16(TUint16 *aHeapCell,TInt aMaxLength);

   535 	IMPORT_C explicit LString16(TUint16 *aHeapCell,TInt aLength,TInt aMaxLength);

   537 	// Assignment thru payload copying

   538 	IMPORT_C LString16& operator=(const TDesC16& aDes);

   539 	IMPORT_C LString16& operator=(const LString16& aDes);

   540 	IMPORT_C LString16& operator=(const TUint16* aZeroTerminatedString);

   542 	// Assignment by transfer of payload to this object;

   543 	// supplied object is destroyed or zeroed.

   544 	IMPORT_C LString16& operator=(HBufC16* aHBuf);

   546 	// Assign by transfer of payload ownership to this object;

   547 	// supplied object is destroyed or zeroed.

   548 	IMPORT_C void Assign(const LString16& aString);

   549 	IMPORT_C void Assign(const RBuf16& aRBuf);

   550 	IMPORT_C void Assign(HBufC16* aHBuf);

   551 	IMPORT_C void Assign(TUint16 *aHeapCell,TInt aMaxLength);

   552 	IMPORT_C void Assign(TUint16 *aHeapCell,TInt aLength,TInt aMaxLength);

   554 	IMPORT_C void CreateL(RReadStream& aStream,TInt aMaxLength);

   556 	IMPORT_C LString16& operator+=(TChar aChar);

   557 	IMPORT_C LString16& operator+=(const TDesC16 &aDes);

   559 	IMPORT_C void CopyL(const TDesC16 &aDes);

   560 	IMPORT_C void CopyL(const TUint16 *aZeroTerminatedString);

   561 	IMPORT_C void CopyL(const TDesC8 &aDes);

   562 	IMPORT_C void CopyL(const TUint16 *aBuf,TInt aLength);

   564  	IMPORT_C void SetLengthL(TInt aLength);

   565  	IMPORT_C void SetMaxLengthL(TInt aMaxLength);

   566 	IMPORT_C void Compress(); // deprecated; to be removed

   567 	IMPORT_C void ReserveFreeCapacityL(TInt aExtraSpaceLength);

   568 	IMPORT_C void Reset();

   570 	IMPORT_C void AppendL(TChar aChar);

   571 	IMPORT_C void AppendL(const TDesC16 &aDes);

   572 	IMPORT_C void AppendL(const TUint16 *aBuf,TInt aLength);

   574 	IMPORT_C void FillL(TChar aChar,TInt aLength);

   575 	IMPORT_C void FillZL(TInt aLength);

   577 	IMPORT_C void NumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth);

   578 	IMPORT_C void AppendNumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth);

   579 	IMPORT_C const TUint16 *PtrZL();

   580 	IMPORT_C void CopyFL(const TDesC16 &aDes);

   581 	IMPORT_C void CopyCL(const TDesC16 &aDes);

   582 	IMPORT_C void CopyLCL(const TDesC16 &aDes);

   583 	IMPORT_C void CopyUCL(const TDesC16 &aDes);

   584 	IMPORT_C void CopyCPL(const TDesC16 &aDes);

   585 	IMPORT_C void AppendFillL(TChar aChar,TInt aLength);

   586 	IMPORT_C void ZeroTerminateL();

   587 	IMPORT_C void SwapL(TDes16 &aDes);

   588 	IMPORT_C void SwapL(LString16 &aDes); // Added overload

   589 	IMPORT_C void InsertL(TInt aPos,const TDesC16 &aDes);

   590 	IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const TDesC16 &aDes);

   591 	IMPORT_C void JustifyL(const TDesC16 &aDes,TInt aWidth,TAlign anAlignment,TChar aFill);

   592 	IMPORT_C void NumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth);

   593 	IMPORT_C void NumUCL(TUint64 aVal, TRadix aRadix=EDecimal);

   594 	IMPORT_C TInt NumL(TReal aVal,const TRealFormat &aFormat) __SOFTFP;

   595 	IMPORT_C void NumL(TInt64 aVal);

   596 	IMPORT_C void NumL(TUint64 aVal, TRadix aRadix);

   597 	IMPORT_C void FormatL(TRefByValue<const TDesC16> aFmt,...);

   598 	IMPORT_C void FormatListL(const TDesC16 &aFmt,VA_LIST aList);

   599 	IMPORT_C void AppendJustifyL(const TDesC16 &Des,TInt aWidth,TAlign anAlignment,TChar aFill);

   600 	IMPORT_C void AppendJustifyL(const TDesC16 &Des,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);

   601 	IMPORT_C void AppendJustifyL(const TUint16 *aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill);

   602 	IMPORT_C void AppendJustifyL(const TUint16 *aString,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);

   603 	IMPORT_C void AppendNumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth);

   604 	IMPORT_C void AppendNumUCL(TUint64 aVal, TRadix aRadix=EDecimal);

   605 	IMPORT_C TInt AppendNumL(TReal aVal,const TRealFormat &aFormat) __SOFTFP;

   606 	IMPORT_C void AppendNumL(TInt64 aVal);

   607 	IMPORT_C void AppendNumL(TUint64 aVal, TRadix aRadix);

   608 	IMPORT_C void AppendFormatL(TRefByValue<const TDesC16> aFmt,...);

   609 	IMPORT_C void AppendFormatListL(const TDesC16 &aFmt,VA_LIST aList);

   611 	using RBuf16::operator==;

   612 	IMPORT_C TBool operator==( const TUint16* aZeroTerminatedString) const;

   613 	using RBuf16::operator<;

   614 	IMPORT_C TBool operator<( const TUint16* aZeroTerminatedString) const;

   615 	using RBuf16::operator<=;

   616 	IMPORT_C TBool operator<=( const TUint16* aZeroTerminatedString) const;

   617 	using RBuf16::operator>;

   618 	IMPORT_C TBool operator>( const TUint16* aZeroTerminatedString) const;

   619 	using RBuf16::operator>=;

   620 	IMPORT_C TBool operator>=( const TUint16* aZeroTerminatedString) const;

   621 	using RBuf16::operator!=;

   622 	IMPORT_C TBool operator!=( const TUint16* aZeroTerminatedString) const;

   623 	using RBuf16::Compare;

   624 	IMPORT_C TInt Compare(const TUint16* aZeroTerminatedString) const;

   625 	using RBuf16::CompareF;

   626 	IMPORT_C TInt CompareF(const TUint16* aZeroTerminatedString) const;

   627 	using RBuf16::Match;

   628 	IMPORT_C TInt Match(const TUint16* aZeroTerminatedString) const;

   629 	using RBuf16::MatchF;

   630 	IMPORT_C TInt MatchF(const TUint16* aZeroTerminatedString) const;

   631 	using RBuf16::Find;

   632 	IMPORT_C TInt Find(const TUint16* aZeroTerminatedString) const;

   633 	using RBuf16::FindF;

   634 	IMPORT_C TInt FindF(const TUint16* aZeroTerminatedString) const;

   636 	IMPORT_C void CopyFL(const TUint16* aZeroTerminatedString);

   637 	IMPORT_C void CopyLCL(const TUint16* aZeroTerminatedString);

   638 	IMPORT_C void CopyUCL(const TUint16* aZeroTerminatedString);

   639 	IMPORT_C void CopyCPL(const TUint16* aZeroTerminatedString);

   640 	IMPORT_C void InsertL(TInt aPos,const TUint16* aZeroTerminatedString);

   641 	IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const TUint16* aZeroTerminatedString);

   642 	IMPORT_C void JustifyL(const TUint16* aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill);

   643 	IMPORT_C void AppendL(const TUint16* aZeroTerminatedString);

   644 	IMPORT_C LString16& operator+=(const TUint16* aZeroTerminatedString);

   646 #ifdef NATIVE_WCHAR

   647 	IMPORT_C LString16(const wchar_t* aWideCharStr);

   649 	IMPORT_C TBool operator==( const wchar_t* aWideCharStr) const;

   650 	IMPORT_C TBool operator<( const wchar_t* aWideCharStr) const;

   651 	IMPORT_C TBool operator<=( const wchar_t* aWideCharStr) const;

   652 	IMPORT_C TBool operator>( const wchar_t* aWideCharStr) const;

   653 	IMPORT_C TBool operator>=( const wchar_t* aWideCharStr) const;

   654 	IMPORT_C TBool operator!=( const wchar_t* aWideCharStr) const;

   655 	IMPORT_C TInt Compare(const wchar_t* aWideCharStr) const;

   656 	IMPORT_C TInt CompareF(const wchar_t* aWideCharStr) const;

   657 	IMPORT_C TInt Match(const wchar_t* aWideCharStr) const;

   658 	IMPORT_C TInt MatchF(const wchar_t* aWideCharStr) const;

   659 	IMPORT_C TInt Find(const wchar_t* aWideCharStr) const;

   660 	IMPORT_C TInt Find(const wchar_t* aWideCharStr,TInt aLenS ) const;

   661 	IMPORT_C TInt FindF(const wchar_t* aWideCharStr) const;

   662 	IMPORT_C TInt FindF(const wchar_t* aWideCharStr,TInt aLenS) const;

   664 	IMPORT_C LString16& operator=(const wchar_t* aWideCharStr);

   665 	IMPORT_C LString16& operator+=(const wchar_t* aWideCharStr);

   666 	IMPORT_C void CopyL(const wchar_t* aWideCharStr);

   667 	IMPORT_C void CopyFL(const wchar_t* aWideCharStr);

   668 	IMPORT_C void CopyLCL(const wchar_t* aWideCharStr);

   669 	IMPORT_C void CopyUCL(const wchar_t* aWideCharStr);

   670 	IMPORT_C void CopyCPL(const wchar_t* aWideCharStr);

   671 	IMPORT_C void InsertL(TInt aPos,const wchar_t* aWideCharStr);

   672 	IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const wchar_t* aWideCharStr);

   673 	IMPORT_C void AppendL(const wchar_t* aWideCharStr, TInt aLength);

   674 	IMPORT_C void AppendL(const wchar_t* aWideCharStr);

   675 	IMPORT_C void JustifyL(const wchar_t* aWideCharStr,TInt aWidth,TAlign anAlignment,TChar aFill);

   676 	IMPORT_C void AppendJustifyL(const wchar_t* aWideCharStr,TInt aWidth,TAlign anAlignment,TChar aFill);

   677 	IMPORT_C void AppendJustifyL(const wchar_t* aWideCharStr,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);

   679 #endif// NATIVE_WCHAR

   682 protected:

   684 private:

   685 	/*

   686 	 * New capacity management API

   687 	 */

   688 	void ReserveL(TInt aMinRequiredCapacity);

   689 	void ReserveCapacityGrowExponentialL(TInt aRequiredCapacity);

   690 	void ReserveCapacityGrowExponentialL();

   691 	void ReserveFreeCapacityGrowExponentialL(TInt aRequiredEmptySpace);

   694 	//----------------------------------------------------------

   695 	// These mutable TDes16 methods panic when called with an insufficient

   696 	// buffer space.

   697 	// A precondition for TDes16 use is that a sufficient

   698 	// sufficient buffer is allocated before making calls that write to the

   699 	// buffer. LString invalidates this precondition.

   700 	// LString inheriting these TDes methods makes it easy

   701 	// for developers to call them inadvertently. They have been made

   702 	// private to ensure the misunderstanding never happens. Developers should

   703 	// use the leaving (L suffixed) LString equivalents.

   704 	void SetLength(TInt aLength);

   705 	void SetMax();

   706 	void Copy(const TDesC8 &aDes);

   707 	void Copy(const TDesC16 &aDes);

   708 	void Copy(const TUint16 *aBuf,TInt aLength);

   709 	void Copy(const TUint16 *aString);

   710 	void Append(TChar aChar);

   711 	void Append(const TDesC16 &aDes);

   712 	void Append(const TUint16 *aBuf,TInt aLength);

   713 	void Fill(TChar aChar,TInt aLength);

   714 	void FillZ(TInt aLength);

   715 	void NumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth);

   716 	void AppendNumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth);

   717 	const TUint16 *PtrZ();

   718 	void CopyF(const TDesC16 &aDes);

   719 	void CopyC(const TDesC16 &aDes);

   720 	void CopyLC(const TDesC16 &aDes);

   721 	void CopyUC(const TDesC16 &aDes);

   722 	void CopyCP(const TDesC16 &aDes);

   723 	void AppendFill(TChar aChar,TInt aLength);

   724 	void ZeroTerminate();

   725 	void Swap(TDes16 &aDes);

   726 	void Insert(TInt aPos,const TDesC16 &aDes);

   727 	void Replace(TInt aPos,TInt aLength,const TDesC16 &aDes);

   728 	void Justify(const TDesC16 &aDes,TInt aWidth,TAlign anAlignment,TChar aFill);

   729 	void NumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth);

   730 	void NumUC(TUint64 aVal, TRadix aRadix=EDecimal);

   731 	TInt Num(TReal aVal,const TRealFormat &aFormat) __SOFTFP;

   732 	void Num(TInt64 aVal);

   733 	void Num(TUint64 aVal, TRadix aRadix);

   734 	void Format(TRefByValue<const TDesC16> aFmt,...);

   735 	void FormatList(const TDesC16 &aFmt,VA_LIST aList);

   736 	void AppendJustify(const TDesC16 &Des,TInt aWidth,TAlign anAlignment,TChar aFill);

   737 	void AppendJustify(const TDesC16 &Des,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);

   738 	void AppendJustify(const TUint16 *aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill);

   739 	void AppendJustify(const TUint16 *aZeroTerminatedString,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);

   740 	void AppendNumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth);

   741 	void AppendNumUC(TUint64 aVal, TRadix aRadix=EDecimal);

   742 	TInt AppendNum(TReal aVal,const TRealFormat &aFormat) __SOFTFP;

   743 	void AppendNum(TInt64 aVal);

   744 	void AppendNum(TUint64 aVal, TRadix aRadix);

   745 	void AppendFormat(TRefByValue<const TDesC16> aFmt,TDes16Overflow *aOverflowHandler,...);

   746 	void AppendFormat(TRefByValue<const TDesC16> aFmt,...);

   747 	void AppendFormatList(const TDesC16 &aFmt,VA_LIST aList,TDes16Overflow *aOverflowHandler=NULL);

   748 	// end of TDes16 methods

   749 	//---------------------------------------------------

   751 	//----------------------------------------------------------

   752 	// These mutable RBuf16 methods have been privatised because

   753 	// they make assumptions which are incompatible with the

   754 	// general use pattern of LString16.

   755 	void Swap(RBuf16& aRBuf);

   756 	TInt Create(TInt aMaxLength);

   757 	void CreateL(TInt aMaxLength);

   758 	TInt CreateMax(TInt aMaxLength);

   759 	void CreateMaxL(TInt aMaxLength);

   760 	TInt Create(const TDesC16& aDes);

   761 	void CreateL(const TDesC16& aDes);

   762 	TInt Create(const TDesC16& aDes,TInt aMaxLength);

   763 	void CreateL(const TDesC16& aDes,TInt aMaxLength);

   764 	void Close();

   765 	void CleanupClosePushL();

   766 	// end of privated RBuf16 methods

   767 	//---------------------------------------------------

   769 	void EnsureCapacityIncrementL(TInt aLengthIncrement);

   770 	void IncreaseCapacityL();

   772 private:

   773 	//reserved data member for future-proofing

   774 	TInt iReserved;

   775 	};

   778 /**

   779 Type alias for LString16.

   781 LString is typically used in preference to LString16 when manipulating

   782 Unicode text, in the same way that TDesC is typically used in

   783 preference to TDesC16.

   784 */

   785 typedef LString16 LString;

   787 /**

   788 Type alias for LString8.

   790 LData can be used to better express intent when using an LString8 to

   791 manipulate raw binary (non character) data.

   792 */

   793 typedef LString8 LData;

   795 #undef LSTRING_CONSTRUCTORS_MAY_LEAVE

   797 #endif // !ESTRING_H

author	sl
	Tue, 10 Jun 2014 14:32:02 +0200
changeset 1	260cb5ec6c19
permissions	-rw-r--r--