1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/ossrv/lowlevellibsandfws/genericusabilitylib/inc/estring.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,797 @@
1.4 +// Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +//
1.18 +
1.19 +#ifndef ESTRING_H
1.20 +#define ESTRING_H
1.21 +
1.22 +#include <e32std.h>
1.23 +
1.24 +// this macro is defined only if the target is WINSCW and wchar_t is ON
1.25 +// (i.e OPTION CW -wchar_t on)
1.26 +// and if the target is any thing other than WINSCW
1.27 +// it is being assumed that wchar_t is ON(OPTION CW -wchar_t on by
1.28 +// default or other wise)
1.29 +#define NATIVE_WCHAR // most platforms do wchar_t properly
1.30 +#if defined __cplusplus && defined __WINSCW__
1.31 +#if !__option(wchar_type) // without the wchar_type option
1.32 +typedef unsigned short wchar_t; // needs a typedef
1.33 +#undef NATIVE_WCHAR // which is not native
1.34 +#endif
1.35 +#endif
1.36 +
1.37 +// Since the LStrings can leave in their constructors, we have to make
1.38 +// sure to avoid the operator new/delete ELeave mismatch problem that
1.39 +// can result in the top level LString object heap being
1.40 +// leaked. These operator delete overloads match the global operator
1.41 +// new overloads applicable to the LString classes (which are
1.42 +// non-CBase derived).
1.43 +//
1.44 +// Note that when allocating a native C++ array of LStrings, only the
1.45 +// default constructor is invoked which cannot leave. So there are no
1.46 +// issues related to the array case.
1.47 +
1.48 +#define LSTRING_CONSTRUCTORS_MAY_LEAVE \
1.49 + static void operator delete(TAny* aPtr) __NO_THROW \
1.50 + { \
1.51 + return ::operator delete(aPtr); \
1.52 + } \
1.53 + \
1.54 + static void operator delete(TAny* aPtr, TLeave) __NO_THROW \
1.55 + { \
1.56 + return ::operator delete(aPtr); \
1.57 + } \
1.58 + \
1.59 + static void operator delete(TAny*, TAny*) __NO_THROW \
1.60 + { \
1.61 + }
1.62 +
1.63 +/**
1.64 + @file
1.65 +
1.66 + A self-managing descriptor class
1.67 +
1.68 + @publishedAll
1.69 + @released
1.70 +*/
1.71 +
1.72 +/**
1.73 +@class LString8
1.74 +
1.75 +LString8 is a convenient, general-purpose 8 bit string class derived
1.76 +from RBuf8. LString8 adds automatic cleanup and on-demand buffer
1.77 +resize facilities.
1.78 +
1.79 +@par L-Classes
1.80 +
1.81 +Note: The L prefix denotes that construction, copying, passing and
1.82 +returning by value, assignment, and manipulation via operators should
1.83 +all be considered potentially leaving operations unless otherwise
1.84 +explicitly documented. Code that uses LString8 should be written
1.85 +accordingly, in leave-safe style.
1.86 +
1.87 +@par Descriptor Relationships
1.88 +
1.89 +Like an RBuf8, an LString8 can be passed to any function that is
1.90 +prototyped to take a TDes8 or a TDesC8 reference. Again like an
1.91 +RBuf8, an LString8 maintains its string data in a heap buffer.
1.92 +
1.93 +@par Value-Type Behaviour
1.94 +
1.95 +Unlike RBuf8, an LString8 may be used much like a simple T class;
1.96 +LString8 typed variables will automatically clean up after themselves
1.97 +when they go out of scope, and LString8 typed fields will similarly
1.98 +automatically release all owned resources when their containing object
1.99 +is destroyed.
1.100 +
1.101 +For example, where:
1.102 +
1.103 +@code
1.104 +RBuf8 buf;
1.105 +buf.CleanupClosePushL();
1.106 +...
1.107 +CleanupStack::PopAndDestroy();
1.108 +@endcode
1.109 +
1.110 +would be required, with LString8:
1.111 +
1.112 +@code
1.113 +LString8 buf;
1.114 +...
1.115 +@endcode
1.116 +
1.117 +will suffice. Pushing an LString8 onto the cleanup stack is not
1.118 +necessary or recommended, but the effects of doing so are
1.119 +benign. LString8 instances can also be passed and returned by value,
1.120 +but note that doing so may trigger implicit heap allocation and cause
1.121 +a leave with KErrNoMemory.
1.122 +
1.123 +@code
1.124 +void TakeString(LString8 aString)
1.125 + {
1.126 + // ...
1.127 + }
1.128 +
1.129 +LString8 ReturnString(LString8 aString)
1.130 + {
1.131 + TakeString(aString); // Statement may leave with KErrNoMemory
1.132 + return aString; // Statement may leave with KErrNoMemory
1.133 + }
1.134 +@endcode
1.135 +
1.136 +As with other descriptors, passing by reference when possible is more
1.137 +efficient.
1.138 +
1.139 +@par On-Demand Growth
1.140 +
1.141 +In addition to the value-type semantics described above, LString8
1.142 +also supports automatic in-place resizing. All standard descriptor
1.143 +methods are available, but for any non-leaving descriptor method that
1.144 +may panic due to buffer overflow, LString8 adds a corresponding
1.145 +leaving method that automatically expands the underlying buffer
1.146 +on-demand. For example, Append() will panic if the new data overflows
1.147 +available buffer space, while AppendL() will attempt to realloc the
1.148 +buffer as necessary. The new leaving variants may therefore leave with
1.149 +KErrNoMemory, may invalidate any existing raw pointers into the data
1.150 +buffer (e.g. those previously returned by Ptr()), and may change the
1.151 +value returned by MaxLength().
1.152 +
1.153 +@code
1.154 +LString8 message; // Zero length
1.155 +message.FormatL(_L("This is message %n from %S"), n, &s); // FormatL automatically grows the buffer
1.156 +User::InfoPrint(message);
1.157 +@endcode
1.158 +
1.159 +It is important to note that LString8 only supports automatic growth
1.160 +when being manipulated directly as an LString8. When an LString8 is
1.161 +passed to a function accepting a TDes8, that function will operate on
1.162 +it as if it is a fixed-max-length descriptor. In that case, adequate
1.163 +capacity must be reserved within the LString8 prior to calling the
1.164 +function. This can either be achieved using the appropriate constructor or ReserveFreeCapacityL().
1.165 +
1.166 +@code
1.167 +extern void GetLastQuery(TDes8& aQuery);
1.168 +extern void GetLastAuxQuery(TDes8& aQuery);
1.169 +
1.170 +LString8 query(KMaxQuerySize); // Guarantees query.MaxLength() >= KMaxQuerySize
1.171 +GetLastQuery(query);
1.172 +
1.173 +// ...
1.174 +
1.175 +previousQueryMaxLength = query.MaxLength();
1.176 +
1.177 +query.ReserveFreeCapacityL(KExtraRequiredSize); // Guarantees query.MaxLength() >= KExtraRequiredSize + previousQueryMaxLength;
1.178 +GetLastAuxQuery(query);
1.179 +
1.180 +@endcode
1.181 +
1.182 +@par Relationship with TDes and RBuf
1.183 +
1.184 +LString8 derives from RBuf8 in order to achieve maximum
1.185 +interoperability with existing descriptor-accepting APIs. This
1.186 +derivation forces some unusual API compromises, however, due to the
1.187 +unique characteristics of LString8 compared to other descriptors.
1.188 +
1.189 +Some of the mutating methods on the base classes, TDes8 and RBuf8,
1.190 +panic when called with insufficient buffer space. Sufficient space is
1.191 +a precondition of these base classes which LString8 relaxes with
1.192 +its capability to start with zero length. LString8 defines new
1.193 +leaving variants of these methods with auto-growth behaviour
1.194 +(e.g. AppendL), but at the same time inherits the original methods
1.195 +(e.g. Append). This makes it too easy for developers to call the
1.196 +wrong method inadvertently. In order to address this, the original
1.197 +non-leaving methods have been made private in LString8. Developers
1.198 +should use the leaving LString8 versions.
1.199 +
1.200 +Note that, if required for any reason, the non-leaving method variants
1.201 +may be accessed by explicitly qualifying the method name to the
1.202 +appropriate parent type. For example: aString.TDes::Append(...). When
1.203 +working with an LString8 but doing so via a TDes& typed variable, all
1.204 +TDes8 APIs are directly available.
1.205 +
1.206 +Hiding these methods does not remove the problem entirely. The same
1.207 +problem can happen if an LString object of insufficient size in passed
1.208 +into a any API accepting a TDes. The advice is that developers always
1.209 +ensure there is sufficient space before passing LString as a TDes.
1.210 +
1.211 +@par Performance Concerns
1.212 +
1.213 +While being simpler to use than existing descriptors in many cases,
1.214 +LString8's use of heap allocation and its resizing variant methods
1.215 +clearly come with associated costs. Their use in performance-critical
1.216 +code should be carefully considered. On the other hand, LString8's
1.217 +small stack footprint and ability to better-handle inputs of
1.218 +unpredictable size may make them a better choice when the alternative
1.219 +is a large, fixed-max-size TBuf or HBufC.
1.220 +
1.221 +@par Buffer Ownership
1.222 +
1.223 +Typically an LString8 will automatically allocate its own buffer, but
1.224 +like RBuf8 it can also take ownership of a pre-existing raw memory
1.225 +buffer or heap descriptor.
1.226 +
1.227 +The class is intended for instantiation.
1.228 +
1.229 +@see RBuf8
1.230 +@see TBuf8
1.231 +@see TPtr8
1.232 +@see HBufC8
1.233 +@see TDesC8
1.234 +@see TDes8
1.235 +@see LString
1.236 +
1.237 +*/
1.238 +class LString8 : public RBuf8
1.239 + {
1.240 +public:
1.241 + /*
1.242 + * We add leaving (auto-resizing) variants of the standard TDes
1.243 + * methods where appropriate, and enhance the behaviour of the
1.244 + * corresponding operators to match
1.245 + */
1.246 +
1.247 + LSTRING_CONSTRUCTORS_MAY_LEAVE
1.248 +
1.249 + IMPORT_C LString8();
1.250 + IMPORT_C ~LString8();
1.251 +
1.252 + // Construct with initial capacity
1.253 + IMPORT_C explicit LString8(TInt aInitialCapacity);
1.254 +
1.255 + // Construct by data copying
1.256 + IMPORT_C LString8(const TDesC8& aDes);
1.257 + IMPORT_C LString8(const TUint8* aZeroTerminatedString);
1.258 + IMPORT_C LString8(const LString8& aDes);
1.259 +
1.260 + // Construction thru transfer of ownership
1.261 + IMPORT_C explicit LString8(HBufC8* aHBuf);
1.262 + IMPORT_C explicit LString8(TUint8 *aHeapCell,TInt aMaxLength);
1.263 + IMPORT_C explicit LString8(TUint8 *aHeapCell,TInt aLength,TInt aMaxLength);
1.264 +
1.265 + // Assignment thru payload copying
1.266 + IMPORT_C LString8& operator=(const TDesC8& aDes);
1.267 + IMPORT_C LString8& operator=(const LString8& aDes);
1.268 + IMPORT_C LString8& operator=(const TUint8* aZeroTerminatedString);
1.269 +
1.270 + // Assignment by transfer of payload to this object;
1.271 + // supplied object is destroyed or zeroed.
1.272 + IMPORT_C LString8& operator=(HBufC8* aHBuf);
1.273 +
1.274 + // Assign by transfer of payload ownership to this object;
1.275 + // supplied object is destroyed or zeroed.
1.276 + IMPORT_C void Assign(const LString8& aString);
1.277 + IMPORT_C void Assign(const RBuf8& aRBuf);
1.278 + IMPORT_C void Assign(HBufC8* aHBuf);
1.279 + IMPORT_C void Assign(TUint8 *aHeapCell,TInt aMaxLength);
1.280 + IMPORT_C void Assign(TUint8 *aHeapCell,TInt aLength,TInt aMaxLength);
1.281 +
1.282 + IMPORT_C void CreateL(RReadStream& aStream,TInt aMaxLength);
1.283 +
1.284 + IMPORT_C LString8& operator+=(TChar aChar);
1.285 + IMPORT_C LString8& operator+=(const TDesC8 &aDes);
1.286 +
1.287 + IMPORT_C void CopyL(const TDesC8 &aDes);
1.288 + IMPORT_C void CopyL(const TDesC16 &aDes);
1.289 + IMPORT_C void CopyL(const TUint8 *aZeroTerminatedString);
1.290 + IMPORT_C void CopyL(const TUint8 *aBuf,TInt aLength);
1.291 +
1.292 + IMPORT_C void SetLengthL(TInt aLength);
1.293 + IMPORT_C void SetMaxLengthL(TInt aMaxLength);
1.294 + IMPORT_C void Compress(); // deprecated; to be removed
1.295 + IMPORT_C void ReserveFreeCapacityL(TInt aExtraSpaceLength);
1.296 + IMPORT_C void Reset();
1.297 +
1.298 + IMPORT_C void AppendL(TChar aChar);
1.299 + IMPORT_C void AppendL(const TDesC8 &aDes);
1.300 + IMPORT_C void AppendL(const TUint8 *aBuf,TInt aLength);
1.301 +
1.302 + IMPORT_C void FillL(TChar aChar,TInt aLength);
1.303 + IMPORT_C void FillZL(TInt aLength);
1.304 +
1.305 + IMPORT_C void NumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth);
1.306 + IMPORT_C void AppendNumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth);
1.307 + IMPORT_C const TUint8 *PtrZL();
1.308 + IMPORT_C void CopyFL(const TDesC8 &aDes);
1.309 + IMPORT_C void CopyCL(const TDesC8 &aDes);
1.310 + IMPORT_C void CopyLCL(const TDesC8 &aDes);
1.311 + IMPORT_C void CopyUCL(const TDesC8 &aDes);
1.312 + IMPORT_C void CopyCPL(const TDesC8 &aDes);
1.313 + IMPORT_C void AppendFillL(TChar aChar,TInt aLength);
1.314 + IMPORT_C void ZeroTerminateL();
1.315 + IMPORT_C void SwapL(TDes8 &aDes);
1.316 + IMPORT_C void SwapL(LString8 &aDes); // Added overload
1.317 + IMPORT_C void InsertL(TInt aPos,const TDesC8 &aDes);
1.318 + IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const TDesC8 &aDes);
1.319 + IMPORT_C void JustifyL(const TDesC8 &aDes,TInt aWidth,TAlign anAlignment,TChar aFill);
1.320 + IMPORT_C void NumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth);
1.321 + IMPORT_C void NumUCL(TUint64 aVal, TRadix aRadix=EDecimal);
1.322 + IMPORT_C TInt NumL(TReal aVal,const TRealFormat &aFormat) __SOFTFP;
1.323 + IMPORT_C void NumL(TInt64 aVal);
1.324 + IMPORT_C void NumL(TUint64 aVal, TRadix aRadix);
1.325 + IMPORT_C void FormatL(TRefByValue<const TDesC8> aFmt,...);
1.326 + IMPORT_C void FormatListL(const TDesC8 &aFmt,VA_LIST aList);
1.327 + IMPORT_C void AppendJustifyL(const TDesC8 &Des,TInt aWidth,TAlign anAlignment,TChar aFill);
1.328 + IMPORT_C void AppendJustifyL(const TDesC8 &Des,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);
1.329 + IMPORT_C void AppendJustifyL(const TUint8 *aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill);
1.330 + IMPORT_C void AppendJustifyL(const TUint8 *aString,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);
1.331 + IMPORT_C void AppendNumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth);
1.332 + IMPORT_C void AppendNumUCL(TUint64 aVal, TRadix aRadix=EDecimal);
1.333 + IMPORT_C TInt AppendNumL(TReal aVal,const TRealFormat &aFormat) __SOFTFP;
1.334 + IMPORT_C void AppendNumL(TInt64 aVal);
1.335 + IMPORT_C void AppendNumL(TUint64 aVal, TRadix aRadix);
1.336 + IMPORT_C void AppendFormatL(TRefByValue<const TDesC8> aFmt,...);
1.337 + IMPORT_C void AppendFormatListL(const TDesC8 &aFmt,VA_LIST aList);
1.338 +
1.339 + using RBuf8::operator==;
1.340 + IMPORT_C TBool operator==( const TUint8* aZeroTerminatedString) const;
1.341 + using RBuf8::operator<;
1.342 + IMPORT_C TBool operator<( const TUint8* aZeroTerminatedString) const;
1.343 + using RBuf8::operator<=;
1.344 + IMPORT_C TBool operator<=( const TUint8* aZeroTerminatedString) const;
1.345 + using RBuf8::operator>;
1.346 + IMPORT_C TBool operator>( const TUint8* aZeroTerminatedString) const;
1.347 + using RBuf8::operator>=;
1.348 + IMPORT_C TBool operator>=( const TUint8* aZeroTerminatedString) const;
1.349 + using RBuf8::operator!=;
1.350 + IMPORT_C TBool operator!=( const TUint8* aZeroTerminatedString) const;
1.351 + using RBuf8::Compare;
1.352 + IMPORT_C TInt Compare(const TUint8* aZeroTerminatedString) const;
1.353 + using RBuf8::CompareF;
1.354 + IMPORT_C TInt CompareF(const TUint8* aZeroTerminatedString) const;
1.355 + using RBuf8::Match;
1.356 + IMPORT_C TInt Match(const TUint8* aZeroTerminatedString) const;
1.357 + using RBuf8::MatchF;
1.358 + IMPORT_C TInt MatchF(const TUint8* aZeroTerminatedString) const;
1.359 + using RBuf8::Find;
1.360 + IMPORT_C TInt Find(const TUint8* aZeroTerminatedString) const;
1.361 + using RBuf8::FindF;
1.362 + IMPORT_C TInt FindF(const TUint8* aZeroTerminatedString) const;
1.363 +
1.364 + IMPORT_C void CopyFL(const TUint8* aZeroTerminatedString);
1.365 + IMPORT_C void CopyLCL(const TUint8* aZeroTerminatedString);
1.366 + IMPORT_C void CopyUCL(const TUint8* aZeroTerminatedString);
1.367 + IMPORT_C void CopyCPL(const TUint8* aZeroTerminatedString);
1.368 + IMPORT_C void InsertL(TInt aPos,const TUint8* aZeroTerminatedString);
1.369 + IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const TUint8* aZeroTerminatedString);
1.370 + IMPORT_C void JustifyL(const TUint8* aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill);
1.371 + IMPORT_C void AppendL(const TUint8* aZeroTerminatedString);
1.372 + IMPORT_C LString8& operator+=(const TUint8* aZeroTerminatedString);
1.373 +
1.374 + IMPORT_C LString8(const char* aCharStr);
1.375 +
1.376 + IMPORT_C TBool operator==( const char* aCharStr) const;
1.377 + IMPORT_C TBool operator<( const char* aCharStr) const;
1.378 + IMPORT_C TBool operator<=( const char* aCharStr) const;
1.379 + IMPORT_C TBool operator>( const char* aCharStr) const;
1.380 + IMPORT_C TBool operator>=( const char* aCharStr) const;
1.381 + IMPORT_C TBool operator!=( const char* aCharStr) const;
1.382 + IMPORT_C TInt Compare(const char* aCharStr) const;
1.383 + IMPORT_C TInt CompareF(const char* aCharStr) const;
1.384 + IMPORT_C TInt Match(const char* aCharStr) const;
1.385 + IMPORT_C TInt MatchF(const char* aCharStr) const;
1.386 + IMPORT_C TInt Find(const char* aCharStr) const;
1.387 + IMPORT_C TInt Find(const char* aCharStr,TInt aLenS ) const;
1.388 + IMPORT_C TInt FindF(const char* aCharStr) const;
1.389 + IMPORT_C TInt FindF(const char* aCharStr,TInt aLenS) const;
1.390 +
1.391 + IMPORT_C LString8& operator=(const char* aCharStr);
1.392 + IMPORT_C LString8& operator+=(const char* aCharStr);
1.393 + IMPORT_C void CopyL(const char* aCharStr);
1.394 + IMPORT_C void CopyFL(const char* aCharStr);
1.395 + IMPORT_C void CopyLCL(const char* aCharStr);
1.396 + IMPORT_C void CopyUCL(const char* aCharStr);
1.397 + IMPORT_C void CopyCPL(const char* aCharStr);
1.398 + IMPORT_C void InsertL(TInt aPos,const char* aCharStr);
1.399 + IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const char* aCharStr);
1.400 + IMPORT_C void AppendL(const char* aCharStr, TInt aLength);
1.401 + IMPORT_C void AppendL(const char *aCharStr );
1.402 + IMPORT_C void JustifyL(const char* aCharStr,TInt aWidth,TAlign anAlignment,TChar aFill);
1.403 + IMPORT_C void AppendJustifyL(const char* aCharStr,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);
1.404 + IMPORT_C void AppendJustifyL(const char* aCharStr,TInt aWidth,TAlign anAlignment,TChar aFill);
1.405 +
1.406 +protected:
1.407 +
1.408 +private:
1.409 + /*
1.410 + * capacity management methods
1.411 + */
1.412 + void ReserveL(TInt aMinRequiredCapacity);
1.413 + void ReserveCapacityGrowExponentialL(TInt aRequiredCapacity);
1.414 + void ReserveCapacityGrowExponentialL();
1.415 + void ReserveFreeCapacityGrowExponentialL(TInt aRequiredEmptySpace);
1.416 +
1.417 +
1.418 + //----------------------------------------------------------
1.419 + // These mutable TDes8 methods panic when called with an insufficient
1.420 + // buffer space.
1.421 + // A precondition for TDes8 use is that a sufficient
1.422 + // sufficient buffer is allocated before making calls that write to the
1.423 + // buffer. LString invalidates this precondition.
1.424 + // LString inheriting these TDes methods makes it easy
1.425 + // for developers to call them inadvertently. They have been made
1.426 + // private to ensure the misunderstanding never happens. Developers should
1.427 + // use the leaving (L suffixed) LString equivalents.
1.428 + void SetLength(TInt aLength);
1.429 + void SetMax();
1.430 + void Copy(const TDesC8 &aDes);
1.431 + void Copy(const TDesC16 &aDes);
1.432 + void Copy(const TUint8 *aBuf,TInt aLength);
1.433 + void Copy(const TUint8 *aString);
1.434 + void Append(TChar aChar);
1.435 + void Append(const TDesC8 &aDes);
1.436 + void Append(const TUint8 *aBuf,TInt aLength);
1.437 + void Fill(TChar aChar,TInt aLength);
1.438 + void FillZ(TInt aLength);
1.439 + void NumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth);
1.440 + void AppendNumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth);
1.441 + const TUint8 *PtrZ();
1.442 + void CopyF(const TDesC8 &aDes);
1.443 + void CopyC(const TDesC8 &aDes);
1.444 + void CopyLC(const TDesC8 &aDes);
1.445 + void CopyUC(const TDesC8 &aDes);
1.446 + void CopyCP(const TDesC8 &aDes);
1.447 + void AppendFill(TChar aChar,TInt aLength);
1.448 + void ZeroTerminate();
1.449 + void Swap(TDes8 &aDes);
1.450 + void Insert(TInt aPos,const TDesC8 &aDes);
1.451 + void Replace(TInt aPos,TInt aLength,const TDesC8 &aDes);
1.452 + void Justify(const TDesC8 &aDes,TInt aWidth,TAlign anAlignment,TChar aFill);
1.453 + void NumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth);
1.454 + void NumUC(TUint64 aVal, TRadix aRadix=EDecimal);
1.455 + TInt Num(TReal aVal,const TRealFormat &aFormat) __SOFTFP;
1.456 + void Num(TInt64 aVal);
1.457 + void Num(TUint64 aVal, TRadix aRadix);
1.458 + void Format(TRefByValue<const TDesC8> aFmt,...);
1.459 + void FormatList(const TDesC8 &aFmt,VA_LIST aList);
1.460 + void AppendJustify(const TDesC8 &Des,TInt aWidth,TAlign anAlignment,TChar aFill);
1.461 + void AppendJustify(const TDesC8 &Des,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);
1.462 + void AppendJustify(const TUint8 *aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill);
1.463 + void AppendJustify(const TUint8 *aZeroTerminatedString,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);
1.464 + void AppendNumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth);
1.465 + void AppendNumUC(TUint64 aVal, TRadix aRadix=EDecimal);
1.466 + TInt AppendNum(TReal aVal,const TRealFormat &aFormat) __SOFTFP;
1.467 + void AppendNum(TInt64 aVal);
1.468 + void AppendNum(TUint64 aVal, TRadix aRadix);
1.469 + void AppendFormat(TRefByValue<const TDesC8> aFmt,TDes8Overflow *aOverflowHandler,...);
1.470 + void AppendFormat(TRefByValue<const TDesC8> aFmt,...);
1.471 + void AppendFormatList(const TDesC8 &aFmt,VA_LIST aList,TDes8Overflow *aOverflowHandler=NULL);
1.472 + // end of TDes8 methods
1.473 + //---------------------------------------------------
1.474 +
1.475 + //----------------------------------------------------------
1.476 + // These mutable RBuf8 methods have been privatised because
1.477 + // they make assumptions which are incompatible with the
1.478 + // general use pattern of LString16.
1.479 + void Swap(RBuf8& aRBuf);
1.480 + TInt Create(TInt aMaxLength);
1.481 + void CreateL(TInt aMaxLength);
1.482 + TInt CreateMax(TInt aMaxLength);
1.483 + void CreateMaxL(TInt aMaxLength);
1.484 + TInt Create(const TDesC8& aDes);
1.485 + void CreateL(const TDesC8& aDes);
1.486 + TInt Create(const TDesC8& aDes,TInt aMaxLength);
1.487 + void CreateL(const TDesC8& aDes,TInt aMaxLength);
1.488 + void Close();
1.489 + void CleanupClosePushL();
1.490 + // end of privated RBuf16 methods
1.491 + //---------------------------------------------------
1.492 +
1.493 + void EnsureCapacityIncrementL(TInt aLengthIncrement);
1.494 + void IncreaseCapacityL();
1.495 +
1.496 +private:
1.497 + //reserved data member for future-proofing
1.498 + TInt iReserved;
1.499 + };
1.500 +
1.501 +/**
1.502 +This is the 16-bit version of LString8. All the comments on LString8 apply equally.
1.503 +
1.504 +@see LString8
1.505 +@see RBuf16
1.506 +@see TBuf16
1.507 +@see TPtr16
1.508 +@see HBufC16
1.509 +@see TDesC16
1.510 +@see TDes16
1.511 +@see LString
1.512 +*/
1.513 +class LString16 : public RBuf16
1.514 + {
1.515 +public:
1.516 + /*
1.517 + * We add leaving (auto-resizing) variants of the standard TDes
1.518 + * methods where appropriate, and enhance the behaviour of the
1.519 + * corresponding operators to match
1.520 + */
1.521 +
1.522 + LSTRING_CONSTRUCTORS_MAY_LEAVE
1.523 +
1.524 + IMPORT_C LString16();
1.525 + IMPORT_C ~LString16();
1.526 +
1.527 + // Construct with initial capacity
1.528 + IMPORT_C explicit LString16(TInt aInitialCapacity);
1.529 +
1.530 + // Construct by data copying
1.531 + IMPORT_C LString16(const TDesC16& aDes);
1.532 + IMPORT_C LString16(const TUint16* aZeroTerminatedString);
1.533 + IMPORT_C LString16(const LString16& aDes);
1.534 +
1.535 + // Construction thru transfer of ownership
1.536 + IMPORT_C explicit LString16(HBufC16* aHBuf);
1.537 + IMPORT_C explicit LString16(TUint16 *aHeapCell,TInt aMaxLength);
1.538 + IMPORT_C explicit LString16(TUint16 *aHeapCell,TInt aLength,TInt aMaxLength);
1.539 +
1.540 + // Assignment thru payload copying
1.541 + IMPORT_C LString16& operator=(const TDesC16& aDes);
1.542 + IMPORT_C LString16& operator=(const LString16& aDes);
1.543 + IMPORT_C LString16& operator=(const TUint16* aZeroTerminatedString);
1.544 +
1.545 + // Assignment by transfer of payload to this object;
1.546 + // supplied object is destroyed or zeroed.
1.547 + IMPORT_C LString16& operator=(HBufC16* aHBuf);
1.548 +
1.549 + // Assign by transfer of payload ownership to this object;
1.550 + // supplied object is destroyed or zeroed.
1.551 + IMPORT_C void Assign(const LString16& aString);
1.552 + IMPORT_C void Assign(const RBuf16& aRBuf);
1.553 + IMPORT_C void Assign(HBufC16* aHBuf);
1.554 + IMPORT_C void Assign(TUint16 *aHeapCell,TInt aMaxLength);
1.555 + IMPORT_C void Assign(TUint16 *aHeapCell,TInt aLength,TInt aMaxLength);
1.556 +
1.557 + IMPORT_C void CreateL(RReadStream& aStream,TInt aMaxLength);
1.558 +
1.559 + IMPORT_C LString16& operator+=(TChar aChar);
1.560 + IMPORT_C LString16& operator+=(const TDesC16 &aDes);
1.561 +
1.562 + IMPORT_C void CopyL(const TDesC16 &aDes);
1.563 + IMPORT_C void CopyL(const TUint16 *aZeroTerminatedString);
1.564 + IMPORT_C void CopyL(const TDesC8 &aDes);
1.565 + IMPORT_C void CopyL(const TUint16 *aBuf,TInt aLength);
1.566 +
1.567 + IMPORT_C void SetLengthL(TInt aLength);
1.568 + IMPORT_C void SetMaxLengthL(TInt aMaxLength);
1.569 + IMPORT_C void Compress(); // deprecated; to be removed
1.570 + IMPORT_C void ReserveFreeCapacityL(TInt aExtraSpaceLength);
1.571 + IMPORT_C void Reset();
1.572 +
1.573 + IMPORT_C void AppendL(TChar aChar);
1.574 + IMPORT_C void AppendL(const TDesC16 &aDes);
1.575 + IMPORT_C void AppendL(const TUint16 *aBuf,TInt aLength);
1.576 +
1.577 + IMPORT_C void FillL(TChar aChar,TInt aLength);
1.578 + IMPORT_C void FillZL(TInt aLength);
1.579 +
1.580 + IMPORT_C void NumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth);
1.581 + IMPORT_C void AppendNumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth);
1.582 + IMPORT_C const TUint16 *PtrZL();
1.583 + IMPORT_C void CopyFL(const TDesC16 &aDes);
1.584 + IMPORT_C void CopyCL(const TDesC16 &aDes);
1.585 + IMPORT_C void CopyLCL(const TDesC16 &aDes);
1.586 + IMPORT_C void CopyUCL(const TDesC16 &aDes);
1.587 + IMPORT_C void CopyCPL(const TDesC16 &aDes);
1.588 + IMPORT_C void AppendFillL(TChar aChar,TInt aLength);
1.589 + IMPORT_C void ZeroTerminateL();
1.590 + IMPORT_C void SwapL(TDes16 &aDes);
1.591 + IMPORT_C void SwapL(LString16 &aDes); // Added overload
1.592 + IMPORT_C void InsertL(TInt aPos,const TDesC16 &aDes);
1.593 + IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const TDesC16 &aDes);
1.594 + IMPORT_C void JustifyL(const TDesC16 &aDes,TInt aWidth,TAlign anAlignment,TChar aFill);
1.595 + IMPORT_C void NumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth);
1.596 + IMPORT_C void NumUCL(TUint64 aVal, TRadix aRadix=EDecimal);
1.597 + IMPORT_C TInt NumL(TReal aVal,const TRealFormat &aFormat) __SOFTFP;
1.598 + IMPORT_C void NumL(TInt64 aVal);
1.599 + IMPORT_C void NumL(TUint64 aVal, TRadix aRadix);
1.600 + IMPORT_C void FormatL(TRefByValue<const TDesC16> aFmt,...);
1.601 + IMPORT_C void FormatListL(const TDesC16 &aFmt,VA_LIST aList);
1.602 + IMPORT_C void AppendJustifyL(const TDesC16 &Des,TInt aWidth,TAlign anAlignment,TChar aFill);
1.603 + IMPORT_C void AppendJustifyL(const TDesC16 &Des,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);
1.604 + IMPORT_C void AppendJustifyL(const TUint16 *aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill);
1.605 + IMPORT_C void AppendJustifyL(const TUint16 *aString,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);
1.606 + IMPORT_C void AppendNumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth);
1.607 + IMPORT_C void AppendNumUCL(TUint64 aVal, TRadix aRadix=EDecimal);
1.608 + IMPORT_C TInt AppendNumL(TReal aVal,const TRealFormat &aFormat) __SOFTFP;
1.609 + IMPORT_C void AppendNumL(TInt64 aVal);
1.610 + IMPORT_C void AppendNumL(TUint64 aVal, TRadix aRadix);
1.611 + IMPORT_C void AppendFormatL(TRefByValue<const TDesC16> aFmt,...);
1.612 + IMPORT_C void AppendFormatListL(const TDesC16 &aFmt,VA_LIST aList);
1.613 +
1.614 + using RBuf16::operator==;
1.615 + IMPORT_C TBool operator==( const TUint16* aZeroTerminatedString) const;
1.616 + using RBuf16::operator<;
1.617 + IMPORT_C TBool operator<( const TUint16* aZeroTerminatedString) const;
1.618 + using RBuf16::operator<=;
1.619 + IMPORT_C TBool operator<=( const TUint16* aZeroTerminatedString) const;
1.620 + using RBuf16::operator>;
1.621 + IMPORT_C TBool operator>( const TUint16* aZeroTerminatedString) const;
1.622 + using RBuf16::operator>=;
1.623 + IMPORT_C TBool operator>=( const TUint16* aZeroTerminatedString) const;
1.624 + using RBuf16::operator!=;
1.625 + IMPORT_C TBool operator!=( const TUint16* aZeroTerminatedString) const;
1.626 + using RBuf16::Compare;
1.627 + IMPORT_C TInt Compare(const TUint16* aZeroTerminatedString) const;
1.628 + using RBuf16::CompareF;
1.629 + IMPORT_C TInt CompareF(const TUint16* aZeroTerminatedString) const;
1.630 + using RBuf16::Match;
1.631 + IMPORT_C TInt Match(const TUint16* aZeroTerminatedString) const;
1.632 + using RBuf16::MatchF;
1.633 + IMPORT_C TInt MatchF(const TUint16* aZeroTerminatedString) const;
1.634 + using RBuf16::Find;
1.635 + IMPORT_C TInt Find(const TUint16* aZeroTerminatedString) const;
1.636 + using RBuf16::FindF;
1.637 + IMPORT_C TInt FindF(const TUint16* aZeroTerminatedString) const;
1.638 +
1.639 + IMPORT_C void CopyFL(const TUint16* aZeroTerminatedString);
1.640 + IMPORT_C void CopyLCL(const TUint16* aZeroTerminatedString);
1.641 + IMPORT_C void CopyUCL(const TUint16* aZeroTerminatedString);
1.642 + IMPORT_C void CopyCPL(const TUint16* aZeroTerminatedString);
1.643 + IMPORT_C void InsertL(TInt aPos,const TUint16* aZeroTerminatedString);
1.644 + IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const TUint16* aZeroTerminatedString);
1.645 + IMPORT_C void JustifyL(const TUint16* aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill);
1.646 + IMPORT_C void AppendL(const TUint16* aZeroTerminatedString);
1.647 + IMPORT_C LString16& operator+=(const TUint16* aZeroTerminatedString);
1.648 +
1.649 +#ifdef NATIVE_WCHAR
1.650 + IMPORT_C LString16(const wchar_t* aWideCharStr);
1.651 +
1.652 + IMPORT_C TBool operator==( const wchar_t* aWideCharStr) const;
1.653 + IMPORT_C TBool operator<( const wchar_t* aWideCharStr) const;
1.654 + IMPORT_C TBool operator<=( const wchar_t* aWideCharStr) const;
1.655 + IMPORT_C TBool operator>( const wchar_t* aWideCharStr) const;
1.656 + IMPORT_C TBool operator>=( const wchar_t* aWideCharStr) const;
1.657 + IMPORT_C TBool operator!=( const wchar_t* aWideCharStr) const;
1.658 + IMPORT_C TInt Compare(const wchar_t* aWideCharStr) const;
1.659 + IMPORT_C TInt CompareF(const wchar_t* aWideCharStr) const;
1.660 + IMPORT_C TInt Match(const wchar_t* aWideCharStr) const;
1.661 + IMPORT_C TInt MatchF(const wchar_t* aWideCharStr) const;
1.662 + IMPORT_C TInt Find(const wchar_t* aWideCharStr) const;
1.663 + IMPORT_C TInt Find(const wchar_t* aWideCharStr,TInt aLenS ) const;
1.664 + IMPORT_C TInt FindF(const wchar_t* aWideCharStr) const;
1.665 + IMPORT_C TInt FindF(const wchar_t* aWideCharStr,TInt aLenS) const;
1.666 +
1.667 + IMPORT_C LString16& operator=(const wchar_t* aWideCharStr);
1.668 + IMPORT_C LString16& operator+=(const wchar_t* aWideCharStr);
1.669 + IMPORT_C void CopyL(const wchar_t* aWideCharStr);
1.670 + IMPORT_C void CopyFL(const wchar_t* aWideCharStr);
1.671 + IMPORT_C void CopyLCL(const wchar_t* aWideCharStr);
1.672 + IMPORT_C void CopyUCL(const wchar_t* aWideCharStr);
1.673 + IMPORT_C void CopyCPL(const wchar_t* aWideCharStr);
1.674 + IMPORT_C void InsertL(TInt aPos,const wchar_t* aWideCharStr);
1.675 + IMPORT_C void ReplaceL(TInt aPos,TInt aLength,const wchar_t* aWideCharStr);
1.676 + IMPORT_C void AppendL(const wchar_t* aWideCharStr, TInt aLength);
1.677 + IMPORT_C void AppendL(const wchar_t* aWideCharStr);
1.678 + IMPORT_C void JustifyL(const wchar_t* aWideCharStr,TInt aWidth,TAlign anAlignment,TChar aFill);
1.679 + IMPORT_C void AppendJustifyL(const wchar_t* aWideCharStr,TInt aWidth,TAlign anAlignment,TChar aFill);
1.680 + IMPORT_C void AppendJustifyL(const wchar_t* aWideCharStr,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);
1.681 +
1.682 +#endif// NATIVE_WCHAR
1.683 +
1.684 +
1.685 +protected:
1.686 +
1.687 +private:
1.688 + /*
1.689 + * New capacity management API
1.690 + */
1.691 + void ReserveL(TInt aMinRequiredCapacity);
1.692 + void ReserveCapacityGrowExponentialL(TInt aRequiredCapacity);
1.693 + void ReserveCapacityGrowExponentialL();
1.694 + void ReserveFreeCapacityGrowExponentialL(TInt aRequiredEmptySpace);
1.695 +
1.696 +
1.697 + //----------------------------------------------------------
1.698 + // These mutable TDes16 methods panic when called with an insufficient
1.699 + // buffer space.
1.700 + // A precondition for TDes16 use is that a sufficient
1.701 + // sufficient buffer is allocated before making calls that write to the
1.702 + // buffer. LString invalidates this precondition.
1.703 + // LString inheriting these TDes methods makes it easy
1.704 + // for developers to call them inadvertently. They have been made
1.705 + // private to ensure the misunderstanding never happens. Developers should
1.706 + // use the leaving (L suffixed) LString equivalents.
1.707 + void SetLength(TInt aLength);
1.708 + void SetMax();
1.709 + void Copy(const TDesC8 &aDes);
1.710 + void Copy(const TDesC16 &aDes);
1.711 + void Copy(const TUint16 *aBuf,TInt aLength);
1.712 + void Copy(const TUint16 *aString);
1.713 + void Append(TChar aChar);
1.714 + void Append(const TDesC16 &aDes);
1.715 + void Append(const TUint16 *aBuf,TInt aLength);
1.716 + void Fill(TChar aChar,TInt aLength);
1.717 + void FillZ(TInt aLength);
1.718 + void NumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth);
1.719 + void AppendNumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth);
1.720 + const TUint16 *PtrZ();
1.721 + void CopyF(const TDesC16 &aDes);
1.722 + void CopyC(const TDesC16 &aDes);
1.723 + void CopyLC(const TDesC16 &aDes);
1.724 + void CopyUC(const TDesC16 &aDes);
1.725 + void CopyCP(const TDesC16 &aDes);
1.726 + void AppendFill(TChar aChar,TInt aLength);
1.727 + void ZeroTerminate();
1.728 + void Swap(TDes16 &aDes);
1.729 + void Insert(TInt aPos,const TDesC16 &aDes);
1.730 + void Replace(TInt aPos,TInt aLength,const TDesC16 &aDes);
1.731 + void Justify(const TDesC16 &aDes,TInt aWidth,TAlign anAlignment,TChar aFill);
1.732 + void NumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth);
1.733 + void NumUC(TUint64 aVal, TRadix aRadix=EDecimal);
1.734 + TInt Num(TReal aVal,const TRealFormat &aFormat) __SOFTFP;
1.735 + void Num(TInt64 aVal);
1.736 + void Num(TUint64 aVal, TRadix aRadix);
1.737 + void Format(TRefByValue<const TDesC16> aFmt,...);
1.738 + void FormatList(const TDesC16 &aFmt,VA_LIST aList);
1.739 + void AppendJustify(const TDesC16 &Des,TInt aWidth,TAlign anAlignment,TChar aFill);
1.740 + void AppendJustify(const TDesC16 &Des,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);
1.741 + void AppendJustify(const TUint16 *aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill);
1.742 + void AppendJustify(const TUint16 *aZeroTerminatedString,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill);
1.743 + void AppendNumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth);
1.744 + void AppendNumUC(TUint64 aVal, TRadix aRadix=EDecimal);
1.745 + TInt AppendNum(TReal aVal,const TRealFormat &aFormat) __SOFTFP;
1.746 + void AppendNum(TInt64 aVal);
1.747 + void AppendNum(TUint64 aVal, TRadix aRadix);
1.748 + void AppendFormat(TRefByValue<const TDesC16> aFmt,TDes16Overflow *aOverflowHandler,...);
1.749 + void AppendFormat(TRefByValue<const TDesC16> aFmt,...);
1.750 + void AppendFormatList(const TDesC16 &aFmt,VA_LIST aList,TDes16Overflow *aOverflowHandler=NULL);
1.751 + // end of TDes16 methods
1.752 + //---------------------------------------------------
1.753 +
1.754 + //----------------------------------------------------------
1.755 + // These mutable RBuf16 methods have been privatised because
1.756 + // they make assumptions which are incompatible with the
1.757 + // general use pattern of LString16.
1.758 + void Swap(RBuf16& aRBuf);
1.759 + TInt Create(TInt aMaxLength);
1.760 + void CreateL(TInt aMaxLength);
1.761 + TInt CreateMax(TInt aMaxLength);
1.762 + void CreateMaxL(TInt aMaxLength);
1.763 + TInt Create(const TDesC16& aDes);
1.764 + void CreateL(const TDesC16& aDes);
1.765 + TInt Create(const TDesC16& aDes,TInt aMaxLength);
1.766 + void CreateL(const TDesC16& aDes,TInt aMaxLength);
1.767 + void Close();
1.768 + void CleanupClosePushL();
1.769 + // end of privated RBuf16 methods
1.770 + //---------------------------------------------------
1.771 +
1.772 + void EnsureCapacityIncrementL(TInt aLengthIncrement);
1.773 + void IncreaseCapacityL();
1.774 +
1.775 +private:
1.776 + //reserved data member for future-proofing
1.777 + TInt iReserved;
1.778 + };
1.779 +
1.780 +
1.781 +/**
1.782 +Type alias for LString16.
1.783 +
1.784 +LString is typically used in preference to LString16 when manipulating
1.785 +Unicode text, in the same way that TDesC is typically used in
1.786 +preference to TDesC16.
1.787 +*/
1.788 +typedef LString16 LString;
1.789 +
1.790 +/**
1.791 +Type alias for LString8.
1.792 +
1.793 +LData can be used to better express intent when using an LString8 to
1.794 +manipulate raw binary (non character) data.
1.795 +*/
1.796 +typedef LString8 LData;
1.797 +
1.798 +#undef LSTRING_CONSTRUCTORS_MAY_LEAVE
1.799 +
1.800 +#endif // !ESTRING_H