1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/kernelhwsrv/kernel/eka/common/des16.cpp Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,4322 @@
1.4 +// Copyright (c) 1994-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 the License "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 +// e32\common\des16.cpp
1.18 +//
1.19 +//
1.20 +
1.21 +#include "common.h"
1.22 +#include <e32des16_private.h>
1.23 +#include <collate.h>
1.24 +#ifdef _UNICODE
1.25 +#include <unicode.h>
1.26 +#include "collateimp.h"
1.27 +#endif
1.28 +#include "CompareImp.h"
1.29 +
1.30 +
1.31 +#define __CHECK_ALIGNMENT(p,c) __ASSERT_DEBUG(!(TUint(p)&1),Des16Panic(c))
1.32 +
1.33 +enum TDes16Panic
1.34 + {
1.35 + ETDesC16ConstructCString=0,
1.36 + ETDesC16ConstructBufLength=1,
1.37 + ETDesC16ConstructBufLengthMax=2,
1.38 + ETDesC16FindPtrLen=3,
1.39 + ETDesC16FindFPtrLen=4,
1.40 + ETDesC16FindCPtrLen=5,
1.41 + ETBufCBase16CopyStringMax=6,
1.42 + EHBufC16AssignCString=7,
1.43 + ETDes16AssignCString=8,
1.44 + ETDes16CopyCString=9,
1.45 + ETDes16CopyBufLength=10,
1.46 + ETDes16AppendBufLength=11,
1.47 + ETDes16RepeatBufLength=12,
1.48 + ETDes16AppendJustify1=13,
1.49 + ETDes16AppendJustify2=14,
1.50 + ETPtrC16SetBufLength=15,
1.51 + ETPtr16SetBufLengthMax=16,
1.52 + ETDesC16Invariant=17,
1.53 + ETDesC16Ptr=18
1.54 + };
1.55 +
1.56 +#ifdef _DEBUG
1.57 +_LIT(KLitDes16Align,"Des16Align");
1.58 +void Des16Panic(TDes16Panic aPanic)
1.59 + {
1.60 + PANIC_CURRENT_THREAD(KLitDes16Align,aPanic);
1.61 + }
1.62 +#endif
1.63 +
1.64 +inline TUint16* memCopy(TUint16* aPtr, const TUint16* aSrc, TInt aLength)
1.65 + {
1.66 + return (TUint16 *)Mem::Copy(aPtr,aSrc,aLength<<1);
1.67 + }
1.68 +
1.69 +#if !defined( __DES16_MACHINE_CODED__) | defined(__EABI_CTORS__)
1.70 +inline TInt StringLength(const TUint16* aPtr)
1.71 + {
1.72 + const TUint16* p = aPtr;
1.73 + while (*p)
1.74 + ++p;
1.75 + return p-aPtr;
1.76 + }
1.77 +#endif
1.78 +
1.79 +inline TDesC16::TDesC16(TInt aType,TInt aLength)
1.80 + :iLength(aLength|(aType<<KShiftDesType16))
1.81 + {}
1.82 +inline TInt TDesC16::Type() const
1.83 +//
1.84 +// Return the descriptor type
1.85 +//
1.86 + {
1.87 + return(iLength>>KShiftDesType16);
1.88 + }
1.89 +
1.90 +inline TDes16::TDes16(TInt aType,TInt aLength,TInt aMaxLength)
1.91 + : TDesC16(aType,aLength),iMaxLength(aMaxLength)
1.92 + {}
1.93 +
1.94 +// Class TBufCBase16
1.95 +inline TBufCBase16::TBufCBase16(TInt aLength)
1.96 + :TDesC16(EBufC,aLength)
1.97 + {}
1.98 +inline TUint16* TBufCBase16::WPtr() const
1.99 + {return const_cast<TUint16*>(Ptr());}
1.100 +
1.101 +#if !defined( __DES16_MACHINE_CODED__) | defined(__EABI_CTORS__)
1.102 +EXPORT_C TPtr16::TPtr16(TBufCBase16& aLcb, TInt aMaxLength)
1.103 + : TDes16(EBufCPtr,aLcb.Length(),aMaxLength),iPtr((TUint16*)&aLcb)
1.104 + {
1.105 + __ASSERT_DEBUG(aLcb.Length()<=aMaxLength,Panic(ETDes16LengthOutOfRange));
1.106 + }
1.107 +#endif
1.108 +
1.109 +#if !defined( __DES16_MACHINE_CODED__)
1.110 +/**
1.111 +Gets a pointer to the data represented by the descriptor.
1.112 +
1.113 +The data cannot be changed through the returned pointer.
1.114 +
1.115 +@return A pointer to the data
1.116 +*/
1.117 +EXPORT_C const TUint16 *TDesC16::Ptr() const
1.118 + {
1.119 +
1.120 + const TUint16* p=NULL;
1.121 + switch (Type())
1.122 + {
1.123 + case EBufC:
1.124 + p=(&((SBufC16 *)this)->buf[0]); break;
1.125 + case EPtrC:
1.126 + p=(((SPtrC16 *)this)->ptr); break;
1.127 + case EPtr:
1.128 + p=(((SPtr16 *)this)->ptr); break;
1.129 + case EBuf:
1.130 + p=(&((SBuf16 *)this)->buf[0]); break;
1.131 + case EBufCPtr:
1.132 + p=(&((SBufCPtr16 *)this)->ptr->buf[0]); break;
1.133 + default:
1.134 + Panic(ETDes16BadDescriptorType);
1.135 + }
1.136 + __CHECK_ALIGNMENT(p,ETDesC16Ptr);
1.137 + return p;
1.138 + }
1.139 +
1.140 +EXPORT_C const TUint16 &TDesC16::AtC(TInt anIndex) const
1.141 +//
1.142 +// Return a reference to the character in the buffer.
1.143 +//
1.144 + {
1.145 +
1.146 + __ASSERT_ALWAYS(anIndex>=0 && anIndex<Length(),Panic(ETDes16IndexOutOfRange));
1.147 + return(Ptr()[anIndex]);
1.148 + }
1.149 +
1.150 +
1.151 +
1.152 +
1.153 +/**
1.154 +Compares this descriptor's data with the specified descriptor's data.
1.155 +
1.156 +The comparison proceeds on a double-byte for double byte basis.
1.157 +The result of the comparison is based on the difference of the first pair
1.158 +of bytes to disagree.
1.159 +
1.160 +Two descriptors are equal if they have the same length and content. Where
1.161 +two descriptors have different lengths and the shorter descriptor's data
1.162 +matches the first part of the longer descriptor's data, the shorter is
1.163 +considered to be less than the longer.
1.164 +
1.165 +@param aDes The 16-bit non-modifable descriptor whose data is to be compared
1.166 + with this descriptor's data.
1.167 +
1.168 +@return Positive. if this descriptor is greater than the specified descriptor.
1.169 + Negative. if this descriptor is less than the specified descriptor.
1.170 + Zero, if both descriptors have the same length and the their contents
1.171 + are the same.
1.172 +*/
1.173 +EXPORT_C TInt TDesC16::Compare(const TDesC16 &aDes) const
1.174 + {
1.175 + return MEM_COMPARE_16(Ptr(),Length(),aDes.Ptr(),aDes.Length());
1.176 + }
1.177 +
1.178 +
1.179 +
1.180 +
1.181 +/**
1.182 +Compares this descriptor's folded data with the specified descriptor's folded
1.183 +data.
1.184 +
1.185 +Note that folding is locale-independent behaviour. It is also important to
1.186 +note that there can be no guarantee that folding is in any way culturally
1.187 +appropriate, and should not be used for comparing strings in natural language;
1.188 +use CompareC() for this.
1.189 +
1.190 +@param aDes The 16-bit non-modifable descriptor whose data is to be compared
1.191 + with this descriptor's data.
1.192 +
1.193 +@return Positive, if this descriptor is greater than the specified descriptor.
1.194 + Negative, if this descriptor is less than the specified descriptor.
1.195 + Zero, if both descriptors have the same length and the their contents
1.196 + are the same.
1.197 +
1.198 +@see TDesC16::Compare()
1.199 +*/
1.200 +EXPORT_C TInt TDesC16::CompareF(const TDesC16 &aDes) const
1.201 + {
1.202 +
1.203 + return(Mem::CompareF(Ptr(),Length(),aDes.Ptr(),aDes.Length()));
1.204 + }
1.205 +
1.206 +
1.207 +
1.208 +
1.209 +/**
1.210 +Compares this descriptor's data with the specified descriptor's data using
1.211 +the standard collation method appropriate to the current locale.
1.212 +
1.213 +@param aDes The 16-bit non-modifable descriptor whose data is to be compared
1.214 + with this descriptor's data.
1.215 +
1.216 +@return Positive, if this descriptor is greater than the specified descriptor.
1.217 + Negative, if this descriptor is less than the specified descriptor.
1.218 + Zero, if the content of both descriptors match.
1.219 +
1.220 +@see TDesC16::Compare()
1.221 +*/
1.222 +EXPORT_C TInt TDesC16::CompareC(const TDesC16 &aDes) const
1.223 + {
1.224 +
1.225 + return(Mem::CompareC(Ptr(),Length(),aDes.Ptr(),aDes.Length()));
1.226 + }
1.227 +#endif
1.228 +
1.229 +
1.230 +
1.231 +
1.232 +#ifdef _UNICODE
1.233 +/**
1.234 +Compares this descriptor's data with the specified descriptor's data to the
1.235 +specified maximum collation level and using the specified collation method.
1.236 +
1.237 +If no collation method is supplied, a default method is used that uses a
1.238 +locale-independent collation table. This means that sorting and matching will
1.239 +not be based on the current locale.
1.240 +
1.241 +This function is only defined for 16-bit (Unicode) build variants. This means
1.242 +that the function is not defined for 8-bit build variants, even when an
1.243 +explicit 16-bit descriptor is used.
1.244 +
1.245 +Strings may match even if the lengths of their respective descriptors are
1.246 +different.
1.247 +
1.248 +@param aDes The 16-bit non-modifable descriptor whose data is to
1.249 + be compared with this descriptor's data.
1.250 +
1.251 +@param aMaxLevel The maximum collation level. This is an integer with
1.252 + values: 0, 1, 2 or 3, which, effectively, determines
1.253 + how 'tight' the matching should be. Level 3 is always
1.254 + used if the aim is to sort strings.
1.255 +
1.256 +@param aCollationMethod A pointer to the collation method or NULL. Collation
1.257 + methods can be retrieved by calls to
1.258 + Mem::CollationMethodByIndex()
1.259 + and Mem::CollationMethodById().
1.260 + Specifying NULL means that the default method is used.
1.261 +
1.262 +@return Positive, if this descriptor is greater than the specified descriptor.
1.263 + Negative, if this descriptor is less than the specified descriptor.
1.264 + Zero, if the content of both descriptors match.
1.265 +
1.266 +@see Mem::CollationMethodByIndex()
1.267 +@see Mem::CollationMethodById()
1.268 +@see TDesC16::Compare()
1.269 +*/
1.270 +EXPORT_C TInt TDesC16::CompareC(const TDesC16& aDes, TInt aMaxLevel, const TCollationMethod* aCollationMethod) const
1.271 + {
1.272 + return Mem::CompareC(Ptr(),Length(),aDes.Ptr(),aDes.Length(),aMaxLevel,aCollationMethod);
1.273 + }
1.274 +
1.275 +/**
1.276 +Get the normalized decomposed form of this 16 bit descriptor
1.277 +@return A pointer to the 16-bit heap buffer containing normalized decomposed form
1.278 + if creation is successful
1.279 +@leave KErrNoMemory if not enough memory to construct the output buffer
1.280 +*/
1.281 +EXPORT_C HBufC16* TDesC16::GetNormalizedDecomposedFormL() const
1.282 + {
1.283 + //pre create a buffer with of size Length
1.284 + TInt strLength=Length();
1.285 + HBufC16* outBuf=HBufC16::NewL(strLength);
1.286 +
1.287 + TUTF32Iterator input(Ptr(),Ptr()+strLength);
1.288 + TCanonicalDecompositionIterator output;
1.289 + output.Set(input);
1.290 +
1.291 + TInt currentAllocateCount=0;
1.292 + TUint16* outPtr = (TUint16* )outBuf->Des().Ptr();
1.293 + TInt preAllocateCount= outBuf->Des().MaxLength();
1.294 +
1.295 + for (;!output.AtEnd();output.Next(),currentAllocateCount++)
1.296 + {
1.297 + if (currentAllocateCount>=preAllocateCount)
1.298 + {
1.299 + const TInt KMaxGrowSize=16;
1.300 + HBufC16* newOutBuf = outBuf->ReAlloc(preAllocateCount+KMaxGrowSize);
1.301 + if(!newOutBuf)
1.302 + {
1.303 + delete outBuf;
1.304 + User::Leave(KErrNoMemory);
1.305 + }
1.306 + outBuf = newOutBuf;
1.307 + outPtr = (TUint16* )outBuf->Des().Ptr();
1.308 + preAllocateCount = outBuf->Des().MaxLength();
1.309 + }
1.310 + outPtr[currentAllocateCount] = (TUint16)(TUint)(output.Current());
1.311 + }
1.312 + // update the length of the buffer...
1.313 + outBuf->Des().SetLength(currentAllocateCount);
1.314 +
1.315 + //compress the unused slot
1.316 + if (currentAllocateCount<preAllocateCount)
1.317 + outBuf = outBuf->ReAlloc(currentAllocateCount); // can't fail to shrink memory
1.318 + return outBuf;
1.319 + }
1.320 +
1.321 +/**
1.322 +Get the folded decomposed form of this 16 bit descriptor
1.323 +@return A pointer to the 16-bit heap buffer containing folded decomposed form
1.324 + if creation is succesful
1.325 +@leave KErrNoMemory if not enough memory to construct the output buffer
1.326 +*/
1.327 +EXPORT_C HBufC16* TDesC16::GetFoldedDecomposedFormL() const
1.328 + {
1.329 + //pre create a buffer with of size Length
1.330 + TInt strLength=Length();
1.331 + HBufC16* outBuf=HBufC16::NewL(strLength);
1.332 +
1.333 + TUTF32Iterator input(Ptr(),Ptr()+strLength);
1.334 + TFoldedCanonicalIterator output (input);
1.335 +
1.336 + TInt currentAllocateCount=0;
1.337 + TUint16* outPtr = (TUint16* )outBuf->Des().Ptr();
1.338 + TInt preAllocateCount= outBuf->Des().MaxLength();
1.339 + const TUnicodeDataSet* charDataSet = GetLocaleCharSet()->iCharDataSet;
1.340 + for (;!output.AtEnd();output.Next(charDataSet),currentAllocateCount++)
1.341 + {
1.342 + if (currentAllocateCount>=preAllocateCount)
1.343 + {
1.344 + const TInt KMaxGrowSize=16;
1.345 + HBufC16* newOutBuf = outBuf->ReAlloc(preAllocateCount+KMaxGrowSize);
1.346 + if(!newOutBuf)
1.347 + {
1.348 + delete outBuf;
1.349 + User::Leave(KErrNoMemory);
1.350 + }
1.351 + outBuf = newOutBuf;
1.352 + outPtr = (TUint16* )outBuf->Des().Ptr();
1.353 + preAllocateCount = outBuf->Des().MaxLength();
1.354 + }
1.355 + outPtr[currentAllocateCount] = (TUint16)(TUint)(output.Current());
1.356 + }
1.357 + // update the length of the buffer...
1.358 + outBuf->Des().SetLength(currentAllocateCount);
1.359 +
1.360 + //compress the unused slot
1.361 + if (currentAllocateCount<preAllocateCount)
1.362 + outBuf = outBuf->ReAlloc(currentAllocateCount); // can't fail to shrink memory
1.363 + return outBuf;
1.364 + }
1.365 +
1.366 +//some utils function
1.367 +static void ResetAndDestroyArray(TAny* aPtr)
1.368 + {
1.369 + (STATIC_CAST(RPointerArray<HBufC8>*,aPtr))->ResetAndDestroy();
1.370 + }
1.371 +
1.372 +/**
1.373 +Get the collation keys of this 16 bit descriptor for a given collation level
1.374 +If no collation method is supplied, a default method is used that uses a
1.375 +locale-independent collation table.
1.376 +@param aMaxLevel The maximum collation level. This is an integer with
1.377 + values: 0, 1, 2 or 3. Level 3 is always
1.378 + used if the aim is to sort strings.
1.379 +@param aCollationMethod A pointer to the collation method or NULL. Collation
1.380 + methods can be retrieved by calls to
1.381 + Mem::CollationMethodByIndex()
1.382 + and Mem::CollationMethodById().
1.383 + Specifying NULL means that the default method is used.
1.384 +@return A pointer to the 8-bit heap buffer containing the collation keys if
1.385 + creation is succesful
1.386 +@leave KErrNoMemory if not enough memory to construct the output buffer
1.387 +*/
1.388 +EXPORT_C HBufC8* TDesC16::GetCollationKeysL(TInt aMaxLevel,const TCollationMethod* aCollationMethod) const
1.389 + {
1.390 + // Clamp the maximum level of the comparison.
1.391 + if(aMaxLevel < 0)
1.392 + aMaxLevel = 0;
1.393 + if(aMaxLevel > 3)
1.394 + aMaxLevel = 3;
1.395 +
1.396 + RPointerArray<HBufC8> levelBuffer;
1.397 + CleanupStack::PushL(TCleanupItem(ResetAndDestroyArray, &levelBuffer));
1.398 + TInt strLength=Length();
1.399 + TInt outputBufferSize=0;
1.400 +
1.401 + //preallocate some initial buffer size as it is not possible to determine the max buffer
1.402 + //required as a character can be further decomposed and each character can possibly
1.403 + //have up to 8 collation keys and this limit might still change.
1.404 + for (TInt i=0;i<=aMaxLevel;i++)
1.405 + {
1.406 + TInt levelKeySize=TCollationKey::MaxSizePerKey(i);
1.407 + HBufC8* buffer=HBufC8::NewLC(strLength*levelKeySize);
1.408 + levelBuffer.AppendL(buffer);
1.409 + CleanupStack::Pop();
1.410 + outputBufferSize+=levelKeySize;
1.411 + }
1.412 + TCollationMethod clm;
1.413 +
1.414 + //if collationMethod is NULL, use the default one
1.415 + if (aCollationMethod==NULL)
1.416 + {
1.417 + clm=*(GetLocaleCharSet()->iCollationDataSet->iMethod);
1.418 + }
1.419 + else
1.420 + {
1.421 + clm = *aCollationMethod;
1.422 + }
1.423 + //if the main table is empty use the standard table
1.424 + if (clm.iMainTable==NULL)
1.425 + clm.iMainTable=StandardCollationMethod();
1.426 +
1.427 + TCollationValueIterator tvi(clm);
1.428 + TUTF32Iterator input(Ptr(),Ptr()+strLength);
1.429 + tvi.SetSourceIt(input);
1.430 +
1.431 + //Expand the buffer by 16 bytes if buffer is exhausted
1.432 + const TInt KMaxBufferGrowSize=16;
1.433 + TInt currentKeyCount=0;
1.434 + TInt preAllocateCount=strLength;
1.435 + TCollationKey collateKey;
1.436 + for (;tvi.GetCurrentKey(collateKey);tvi.Increment(),currentKeyCount++)
1.437 + {
1.438 + for (TInt i=0;i<=aMaxLevel;i++)
1.439 + {
1.440 + if (currentKeyCount==preAllocateCount)
1.441 + levelBuffer[i]=levelBuffer[i]->ReAllocL((currentKeyCount+KMaxBufferGrowSize)*TCollationKey::MaxSizePerKey(i));
1.442 +
1.443 + collateKey.AppendToDescriptor(levelBuffer[i]->Des(),i);
1.444 + }
1.445 + if (currentKeyCount==preAllocateCount)
1.446 + preAllocateCount+=KMaxBufferGrowSize;
1.447 + }
1.448 + //append the level separator which is a "\x00\x00" for level 0 and \x00 for other level
1.449 + outputBufferSize=(outputBufferSize*currentKeyCount)+(aMaxLevel==0?0:4+(aMaxLevel-1)*2);
1.450 + HBufC8* outputResult=HBufC8::NewL(outputBufferSize);
1.451 + TPtr8 outputResultPtr(outputResult->Des());
1.452 + for (TInt count=0;count<=aMaxLevel;count++)
1.453 + {
1.454 + outputResultPtr.Append(*levelBuffer[count]);
1.455 + if (count!=aMaxLevel)
1.456 + {
1.457 + if (count==0)
1.458 + outputResultPtr.Append(0);
1.459 + outputResultPtr.Append(0);
1.460 + }
1.461 + }
1.462 + CleanupStack::PopAndDestroy();
1.463 + return outputResult;
1.464 + }
1.465 +
1.466 +#endif
1.467 +
1.468 +/**
1.469 +Searches for the first occurrence of the specified data sequence within this
1.470 +descriptor.
1.471 +
1.472 +Searching always starts at the beginning of this descriptor's data.
1.473 +
1.474 +@param pS A pointer to a location containing the data sequence to be searched
1.475 + for.
1.476 +
1.477 +@param aLenS The length of the data sequence to be searched for. This value
1.478 + must not be negative, otherwise the function raises a panic.
1.479 +
1.480 +@return The offset of the data sequence from the beginning of this descriptor's
1.481 + data. KErrNotFound, if the data sequence cannot be found.
1.482 +
1.483 +@panic USER 17 if aLenS is negative.
1.484 +*/
1.485 +EXPORT_C TInt TDesC16::Find(const TUint16 *pS,TInt aLenS) const
1.486 + {
1.487 +
1.488 + if (!aLenS)
1.489 + return(0);
1.490 + __ASSERT_ALWAYS(aLenS>0,Panic(ETDes16LengthNegative));
1.491 + __CHECK_ALIGNMENT(pS,ETDesC16FindPtrLen);
1.492 + const TUint16 *pB=Ptr();
1.493 + TInt aLenB=Length();
1.494 + const TUint16 *pC=pB-1; // using pre-increment addressing
1.495 + TInt i=aLenB-aLenS;
1.496 + if (i>=0)
1.497 + {
1.498 + const TUint16* pEndS=pS+aLenS-1; // using pre-increment addressing
1.499 + const TUint16 *pEndB=pB+i; // using pre-increment addressing
1.500 + TUint s=*pS;
1.501 + for (;;)
1.502 + {
1.503 + do
1.504 + {
1.505 + if (pC==pEndB)
1.506 + return KErrNotFound;
1.507 + } while (*++pC!=s);
1.508 + const TUint16 *p1=pC;
1.509 + const TUint16 *p2=pS;
1.510 + do
1.511 + {
1.512 + if (p2==pEndS)
1.513 + return (pC-pB);
1.514 + } while (*++p1==*++p2);
1.515 + }
1.516 + }
1.517 + return(KErrNotFound);
1.518 + }
1.519 +
1.520 +
1.521 +
1.522 +
1.523 +/**
1.524 +Searches for the first occurrence of the specified data sequence within this
1.525 +descriptor.
1.526 +
1.527 +Searching always starts at the beginning of this descriptor's
1.528 +data.
1.529 +
1.530 +@param aDes The 16-bit non-modifiable descriptor containing the data sequence
1.531 + to be searched for.
1.532 +
1.533 +@return The offset of the data sequence from the beginning of this descriptor's
1.534 + data. KErrNotFound, if the data sequence cannot be found.
1.535 +*/
1.536 +EXPORT_C TInt TDesC16::Find(const TDesC16 &aDes) const
1.537 + {
1.538 +
1.539 + return(Find(aDes.Ptr(),aDes.Length()));
1.540 + }
1.541 +
1.542 +
1.543 +
1.544 +
1.545 +/**
1.546 +Searches for the first occurrence of the specified folded data sequence within
1.547 +this descriptor's folded data.
1.548 +
1.549 +Searching always starts at the beginning of this descriptor's data.
1.550 +
1.551 +Note that folding is locale-independent behaviour. It is also important to
1.552 +note that there can be no guarantee that folding is in any way culturally
1.553 +appropriate, and should not be used for finding strings in natural language;
1.554 +use FindC() for this.
1.555 +
1.556 +@param pS A pointer to a location containing the data sequence to be
1.557 + searched for.
1.558 +@param aLenS The length of the data sequence to be searched for. This value
1.559 + must not be negative, otherwise the function raises a panic.
1.560 +
1.561 +@return The offset of the data sequence from the beginning of this descriptor's
1.562 + data. KErrNotFound, if the data sequence cannot be found. Zero, if the
1.563 + length of the search data sequence is zero.
1.564 +
1.565 +@panic USER 17 if aLenS is negative
1.566 +
1.567 +@see TDesC16::FindC()
1.568 +*/
1.569 +EXPORT_C TInt TDesC16::FindF(const TUint16 *pS,TInt aLenS) const
1.570 + {
1.571 + __CHECK_ALIGNMENT(pS,ETDesC16FindFPtrLen);
1.572 + TUTF32Iterator candidateStrIt(Ptr(), Ptr() + Length());
1.573 + TUTF32Iterator searchTermIt(pS, pS + aLenS);
1.574 + return ::FindFolded(candidateStrIt, searchTermIt);
1.575 + }
1.576 +
1.577 +
1.578 +
1.579 +
1.580 +/**
1.581 +Searches for the first occurrence of the specified folded data sequence within
1.582 +this descriptor's folded data.
1.583 +
1.584 +Searching always starts at the beginning of this descriptor's data.
1.585 +
1.586 +Note that folding is locale-independent behaviour. It is also important to
1.587 +note that there can be no guarantee that folding is in any way culturally
1.588 +appropriate, and should not be used for finding strings in natural language;
1.589 +use FindC() for this.
1.590 +
1.591 +@param aDes The 16-bit non-modifable descriptor containing the data sequence
1.592 + to be searched for.
1.593 +
1.594 +@return The offset of the data sequence from the beginning of this descriptor's
1.595 + data. KErrNotFound, if the data sequence cannot be found.
1.596 + Zero, if the length of the search data sequence is zero.
1.597 +
1.598 +@see TDesC16::FindC()
1.599 +*/
1.600 +EXPORT_C TInt TDesC16::FindF(const TDesC16 &aDes) const
1.601 + {
1.602 + TUTF32Iterator candidateStrIt(Ptr(), Ptr() + Length());
1.603 + TUTF32Iterator searchTermIt(aDes.Ptr(), aDes.Ptr() + aDes.Length());
1.604 + return ::FindFolded(candidateStrIt, searchTermIt);
1.605 + }
1.606 +
1.607 +
1.608 +
1.609 +
1.610 +/**
1.611 +Searches for the first occurrence of the specified collated data sequence within
1.612 +this descriptor's collated data.
1.613 +
1.614 +Searching always starts at the beginning of this descriptor's data. The function
1.615 +uses the standard collation method appropriate to the current locale.
1.616 +
1.617 +@param aText A pointer to a location containing the data sequence to be
1.618 + searched for.
1.619 +@param aLength The length of the data sequence to be searched for.
1.620 +
1.621 +@return The offset of the data sequence from the beginning of this descriptor's data.
1.622 + KErrNotFound, if the data sequence cannot be found.
1.623 +
1.624 +@panic USER 17 if aLength is negative.
1.625 +*/
1.626 +EXPORT_C TInt TDesC16::FindC(const TUint16 *aText,TInt aLength) const
1.627 + {
1.628 + __CHECK_ALIGNMENT(aText,ETDesC16FindCPtrLen);
1.629 +
1.630 + TCollate c(GetLocaleCharSet(),TCollationMethod::EIgnoreNone | TCollationMethod::EFoldCase);
1.631 + return c.Find(Ptr(),Length(),aText,aLength,1);
1.632 + }
1.633 +
1.634 +
1.635 +
1.636 +
1.637 +/**
1.638 +Searches for the first occurrence of the specified collated data sequence
1.639 +within this descriptor's collated data to the specified maximum collation
1.640 +level.
1.641 +
1.642 +@param aText A pointer to a location containing the data sequence to
1.643 + be searched for.
1.644 +
1.645 +@param aLength The length of the data sequence to be searched for.
1.646 +
1.647 +@param aMaxLevel The maximum collation level. This is an integer with
1.648 + values: 0, 1, 2 or 3, which, effectively, determines
1.649 + how 'tight' the matching should be. Level 3 is always
1.650 + used if the aim is to sort strings.
1.651 +
1.652 +@return The offset of the data sequence from the beginning of this descriptor's data.
1.653 + KErrNotFound, if the data sequence cannot be found.
1.654 +*/
1.655 +EXPORT_C TInt TDesC16::FindC(const TUint16 *aText,TInt aLength, TInt aMaxLevel) const
1.656 +
1.657 + {
1.658 + __CHECK_ALIGNMENT(aText,ETDesC16FindCPtrLen);
1.659 +
1.660 + TCollate c(GetLocaleCharSet(),TCollationMethod::EIgnoreNone | TCollationMethod::EFoldCase);
1.661 + return c.Find(Ptr(),Length(),aText,aLength,aMaxLevel);
1.662 + }
1.663 +
1.664 +
1.665 +
1.666 +
1.667 +/**
1.668 +Searches for the first occurrence of the specified collated data sequence
1.669 +within this descriptor's collated data.
1.670 +
1.671 +Searching always starts at the beginning of this descriptor's data. The
1.672 +function uses the standard collation method appropriate to the current
1.673 +locale.
1.674 +
1.675 +@param aDes The 16-bit non-modifable descriptor containing the data sequence
1.676 + to be searched for.
1.677 +
1.678 +@return The offset of the data sequence from the beginning of this descriptor's
1.679 + data. KErrNotFound, if the data sequence cannot be found.
1.680 +*/
1.681 +EXPORT_C TInt TDesC16::FindC(const TDesC16 &aDes) const
1.682 + {
1.683 +
1.684 + return(FindC(aDes.Ptr(),aDes.Length()));
1.685 + }
1.686 +
1.687 +/**
1.688 +Searches for the first occurrence of the specified collated data sequence
1.689 +within this descriptor's collated data.
1.690 +
1.691 +Searching always starts at the beginning of this descriptor's data. The
1.692 +function uses the standard collation method appropriate to the current
1.693 +locale.
1.694 +
1.695 +@param aDes The 16-bit non-modifable descriptor containing the data sequence
1.696 + to be searched for.
1.697 +
1.698 +@param aLengthFound A refernce to the maximal length of the match found in the candidate
1.699 + string. KErrNotFound, if the data sequence cannot be found.
1.700 +
1.701 +@param aCollationMethod A pointer to the collation method or NULL. Collation
1.702 + methods can be retrieved by calls to
1.703 + Mem::CollationMethodByIndex()
1.704 + and Mem::CollationMethodById().
1.705 + Specifying NULL means that the default method is used.
1.706 +
1.707 +@param aMaxLevel The maximum collation level. This is an integer with
1.708 + values: 0, 1, 2 or 3, which, effectively, determines
1.709 + how 'tight' the matching should be. Level 3 is always
1.710 + used if the aim is to sort strings.
1.711 +
1.712 +@return The offset of the data sequence from the beginning of this descriptor's
1.713 + data. KErrNotFound, if the data sequence cannot be found.
1.714 +*/
1.715 +EXPORT_C TInt TDesC16::FindC(const TDesC16 &aDes, TInt &aLengthFound, const TCollationMethod &aMethod, TInt aMaxLevel) const
1.716 + {
1.717 + TCollate c(aMethod);
1.718 + return c.Find(Ptr(),Length(),aDes.Ptr(),aDes.Length(),aLengthFound,aMaxLevel);
1.719 + }
1.720 +
1.721 +
1.722 +#ifdef _UNICODE
1.723 +LOCAL_C const TText* convTable(TMatchType aType)
1.724 + {
1.725 + switch (aType)
1.726 + {
1.727 + case EMatchFolded: // at present, folding is...
1.728 + case EMatchCollated: return (const TText *)(TChar::EFoldStandard); // ...the same as collation: use all folding methods
1.729 + default: return 0;
1.730 + }
1.731 + }
1.732 +#else
1.733 +LOCAL_C const TText* convTable(TMatchType aType)
1.734 + {
1.735 + switch (aType)
1.736 + {
1.737 + case EMatchFolded: return Locl::FoldTable();
1.738 + case EMatchCollated: return Locl::CollTable();
1.739 + default: return NULL;
1.740 + }
1.741 + }
1.742 +#endif
1.743 +
1.744 +inline TUint conv(const TUint16* aStr,const TText *aConv, const TUnicodeDataSet* aCharDataSet)
1.745 +//
1.746 +// If aConv is not NULL then convert the character.
1.747 +//
1.748 + {
1.749 +
1.750 +#ifdef _UNICODE
1.751 + if (aConv)
1.752 + return TUnicode(*aStr).Fold((TInt)aConv, aCharDataSet);
1.753 + else
1.754 + return *aStr;
1.755 +#else
1.756 + TUint c=*aStr;
1.757 + return aConv && c<0x100 ? aConv[c] : c;
1.758 +#endif
1.759 + }
1.760 +
1.761 +inline TUint lookup(const TUint16* aStr,const TText *aConv)
1.762 + {
1.763 +#ifdef _UNICODE
1.764 + return TUnicode(*aStr).Fold((TInt)aConv,GetLocaleCharSet()->iCharDataSet);
1.765 +#else
1.766 + TUint c=*aStr;
1.767 + return c<0x100 ? aConv[c] : c;
1.768 +#endif
1.769 + }
1.770 +
1.771 +TInt DoMatch16(const TDesC16 &aLeftD,const TDesC16 &aRightD,TMatchType aType)
1.772 + {
1.773 + const TText* table=convTable(aType);
1.774 + const TUint16* pRight=aRightD.Ptr();
1.775 + const TUint16* pM=pRight-1; // pre-increment addressing
1.776 + const TUint16* pP=pM+aRightD.Length();
1.777 + const TUint16* pLeft=aLeftD.Ptr()-1; // pre-increment addressing
1.778 + const TUint16* pB=pLeft;
1.779 + const TUint16* pE=pB+aLeftD.Length();
1.780 +
1.781 +
1.782 + const TUnicodeDataSet* charDataSet = GetLocaleCharSet()->iCharDataSet;
1.783 +
1.784 + // Match any pattern up to the first star
1.785 + TUint c;
1.786 + for (;;)
1.787 + {
1.788 + if (pM==pP) // exhausted the pattern
1.789 + return pB==pE ? 0 : KErrNotFound;
1.790 + TUint c=conv(++pM,table, charDataSet);
1.791 + if (c==KMatchAny)
1.792 + break;
1.793 + if (pB==pE) // no more input
1.794 + return KErrNotFound;
1.795 + if (c!=conv(++pB,table, charDataSet) && c!=KMatchOne) // match failed
1.796 + return KErrNotFound;
1.797 + }
1.798 + // reached a star
1.799 + if (pM==pP)
1.800 + return 0;
1.801 + TInt r=pM==pRight ? -1 : 0;
1.802 + for (;;)
1.803 + {
1.804 + c=conv(++pM,table, charDataSet);
1.805 + if (c==KMatchAny)
1.806 + {
1.807 +star: if (pM==pP) // star at end of pattern, always matches
1.808 + return Max(r,0);
1.809 + if (r<-1) // skipped some '?', matches at beginning
1.810 + r=0;
1.811 + continue;
1.812 + }
1.813 + if (pB==pE) // no more input
1.814 + return KErrNotFound;
1.815 + if (c==KMatchOne)
1.816 + { // skip a character in the input
1.817 + if (pM==pP)
1.818 + return r+((r>=0) ? 0 : (pE-pLeft));
1.819 + ++pB;
1.820 + if (r<0)
1.821 + --r;
1.822 + continue;
1.823 + }
1.824 + // Matching a non-wild character
1.825 + for (;;)
1.826 + {
1.827 + if (table)
1.828 + {
1.829 + while (lookup(++pB,table)!=c)
1.830 + {
1.831 + if (pB==pE) // no more input
1.832 + return KErrNotFound;
1.833 + }
1.834 + }
1.835 + else
1.836 + {
1.837 + while (*++pB!=c)
1.838 + {
1.839 + if (pB==pE) // no more input
1.840 + return KErrNotFound;
1.841 + }
1.842 + }
1.843 + // Try to match up to the next star
1.844 + const TUint16* pb=pB;
1.845 + const TUint16* pm=pM;
1.846 + for (;;)
1.847 + {
1.848 + if (pm<pP)
1.849 + {
1.850 + TUint cc=conv(++pm,table, charDataSet);
1.851 + if (cc==KMatchAny)
1.852 + { // sub-match successful, back to main loop
1.853 + r+=(r>=0 ? 0 : pB-pLeft);
1.854 + pB=pb;
1.855 + pM=pm;
1.856 + goto star;
1.857 + }
1.858 + if (pb==pE)
1.859 + return KErrNotFound; // no more input
1.860 + if (cc!=conv(++pb,table, charDataSet) && cc!=KMatchOne)
1.861 + break; // sub-match failed, try next input character
1.862 + }
1.863 + else if (pb==pE) // end of matching pattern
1.864 + return r+(r>=0 ? 0 : pB-pLeft); // end of input, so have a match
1.865 + else
1.866 + break; // try next input character
1.867 + }
1.868 + }
1.869 + }
1.870 + }
1.871 +
1.872 +
1.873 +
1.874 +EXPORT_C TDesC16::TPrefix TDesC16::HasPrefixC(const TDesC16& aPossiblePrefix,
1.875 + TInt aLevel, const TCollationMethod* aCollationMethod) const
1.876 +/**
1.877 +Compares aPossiblePrefix against the start of the descriptor, using a
1.878 +collated comparison.
1.879 +
1.880 +@param aLevel The maximum level at which to perform the collation.
1.881 +
1.882 + 0: Only check character identities.
1.883 +
1.884 + 1: Check accents as well.
1.885 +
1.886 + 2: Check case as well.
1.887 +
1.888 + 3: Check Unicode values.
1.889 +
1.890 + Currently only level 0 is supported.
1.891 +
1.892 +@param aCollationMethod The collation method to be used for the matching.
1.893 +
1.894 +@return EIsPrefix, if aPossiblePrefix can be extended to
1.895 + be equivalent to the text at the start of this descriptor.
1.896 + EIsNotPrefix if aPossiblePrefix cannot
1.897 + be extended to be equivalent to the text at the start of this descriptor.
1.898 + EMightBePrefix if it currently does not seem to be a prefix, but it
1.899 + is possible that it could be extended to become equivalent to text at
1.900 + the start of this descriptor.
1.901 + EMightBePrefix is returned in cases where it would be expensive
1.902 + to determine for sure.
1.903 +*/
1.904 + {
1.905 + const TText16* lp = aPossiblePrefix.Ptr();
1.906 + const TText16* rp = Ptr();
1.907 + TInt ll = aPossiblePrefix.Length();
1.908 + TInt rl = Length();
1.909 + TInt r;
1.910 + if (!aCollationMethod)
1.911 + {
1.912 + TCollate c(GetLocaleCharSet());
1.913 + r = c.Compare(rp, rl, lp, ll, aLevel);
1.914 + }
1.915 + else
1.916 + {
1.917 + TCollate c(*aCollationMethod);
1.918 + r = c.Compare(rp, rl, lp, ll, aLevel);
1.919 + }
1.920 + return r == 1 || r == 0? EIsPrefix : EIsNotPrefix;
1.921 + }
1.922 +
1.923 +EXPORT_C TInt TDesC16::Match(const TDesC16 &aDes) const
1.924 +/**
1.925 +Searches this descriptor's data for a match with the match pattern supplied
1.926 +in the specified descriptor.
1.927 +
1.928 +The match pattern can contain the wildcard characters "*" and "?", where "*"
1.929 +matches zero or more consecutive occurrences of any character and "?" matches
1.930 +a single occurrence of any character.
1.931 +
1.932 +Note that there is no 'escape character', which means that it is not possible
1.933 +to match either the "*" character itself or the "?" character itself using
1.934 +this function.
1.935 +
1.936 +@param aDes A 16-bit non-modifable descriptor containing the match pattern.
1.937 +
1.938 +@return If a match is found, the offset within this descriptor's data where
1.939 + the match first occurs. KErrNotFound, if there is no match.
1.940 +*/
1.941 + {
1.942 +
1.943 + return DoMatch16(*this,aDes,EMatchNormal);
1.944 +
1.945 + }
1.946 +
1.947 +EXPORT_C TInt TDesC16::MatchF(const TDesC16 &aDes) const
1.948 +/**
1.949 +Searches this descriptor's folded data for a match with the folded match pattern
1.950 +supplied in the specified descriptor.
1.951 +
1.952 +The match pattern can contain the wildcard characters "*" and "?", where "*"
1.953 +matches zero or more consecutive occurrences of any character and "?" matches
1.954 +a single occurrence of any character.
1.955 +
1.956 +Note that folding is locale-independent behaviour. It is also important to
1.957 +note that there can be no guarantee that folding is in any way culturally
1.958 +appropriate, and should not be used for matching strings in natural language;
1.959 +use MatchC() for this.
1.960 +
1.961 +Note that there is no 'escape character', which means that it is not possible
1.962 +to match either the "*" character itself or the "?" character itself using
1.963 +this function.
1.964 +
1.965 +@param aDes A 16-bit non-modifable descriptor containing the match pattern.
1.966 +
1.967 +@return If a match is found, the offset within this descriptor's data where
1.968 + the match first occurs. KErrNotFound, if there is no match.
1.969 +
1.970 +@see TDesC16::MatchC()
1.971 +*/
1.972 + {
1.973 + const TText16* csp = Ptr();
1.974 + const TText16* stp = aDes.Ptr();
1.975 + return LocateMatchStringFolded(csp, csp + Length(), stp, stp + aDes.Length());
1.976 + }
1.977 +
1.978 +EXPORT_C TInt TDesC16::MatchC(const TDesC16 &aPattern) const
1.979 +/**
1.980 +Searches this descriptor's collated data for a match with the collated match
1.981 +pattern supplied in the specified descriptor.
1.982 +
1.983 +The function uses the standard collation method appropriate to
1.984 +the current locale.
1.985 +
1.986 +The match pattern can contain the wildcard characters "*" and "?", where "*"
1.987 +matches zero or more consecutive occurrences of any character and "?" matches
1.988 +a single occurrence of any character.
1.989 +
1.990 +Note that there is no 'escape character', which means that it is not possible
1.991 +to match either the "*" character itself or the "?" character itself using
1.992 +this function.
1.993 +
1.994 +@param aPattern A 16-bit non-modifable descriptor containing the match pattern.
1.995 +
1.996 +@return If a match is found, the offset within this descriptor's data where
1.997 + the match first occurs. KErrNotFound, if there is no match.
1.998 +*/
1.999 + {
1.1000 + TCollationMethod m=*Mem::GetDefaultMatchingTable();
1.1001 + m.iFlags |= (TCollationMethod::EIgnoreNone | TCollationMethod::EFoldCase);
1.1002 + TCollate c(m);
1.1003 + return c.Match(Ptr(), Length(), aPattern.Ptr(), aPattern.Length(), 0, '?', '*');
1.1004 + }
1.1005 +
1.1006 +/**
1.1007 +Searches this descriptor's collated data for a match with the collated match
1.1008 +pattern supplied in the specified descriptor.
1.1009 +
1.1010 +The function uses the standard collation method appropriate to
1.1011 +the current locale.
1.1012 +
1.1013 +The match pattern can contain the wildcard characters specified by aWildChar and aWildSequenceChar
1.1014 +parameters, where aWildSequenceChar matches zero or more consecutive occurrences of any character and
1.1015 +aWildChar matches a single occurrence of any character.
1.1016 +
1.1017 +@param aPattern A 16-bit non-modifable descriptor containing the match pattern.
1.1018 +@param aWildChar Wild card character which may be specified for aSearchTerm.
1.1019 +@param aWildSequenceChar Wild card sequence character which may be specified for aSearchTerm.
1.1020 +@param aEscapeChar The escape character, or 0 if there is to be none. The escape character removes any
1.1021 + special meaning from the subsequent character. For example, if the escape, wild card
1.1022 + and wild sequence characters are \, ? And * respectively, the search term "\?\*\\" matches
1.1023 + only the candidate string "?*\";
1.1024 +@param aMaxLevel Determines the tightness of the collation. At level 0, only
1.1025 + character identities are distinguished. At level 1 accents are
1.1026 + distinguished as well. At level 2 case is distinguishes as well. At
1.1027 + level 3 all valid different Unicode characters are considered different.
1.1028 +@param aCollationMethod A pointer to the collation method or NULL. Collation methods can be retrieved by calls to
1.1029 + Mem::CollationMethodByIndex() and Mem::CollationMethodById().
1.1030 + Specifying NULL means that the default method is used.
1.1031 +
1.1032 +@return If a match is found, the offset within this descriptor's data where
1.1033 + the match first occurs. KErrNotFound, if there is no match.
1.1034 +*/
1.1035 +EXPORT_C TInt TDesC16::MatchC(const TDesC16 &aPattern, TInt aWildChar, TInt aWildSequenceChar,
1.1036 + TInt aEscapeChar, TInt aMaxLevel, const TCollationMethod* aCollationMethod) const
1.1037 + {
1.1038 + TCollationMethod m(aCollationMethod ? *aCollationMethod : *Mem::GetDefaultMatchingTable());
1.1039 + m.iFlags |= (TCollationMethod::EIgnoreNone | TCollationMethod::EFoldCase);
1.1040 + TCollate c(m);
1.1041 + return c.Match(Ptr(), Length(), aPattern.Ptr(), aPattern.Length(), aMaxLevel, aWildChar, aWildSequenceChar, aEscapeChar);
1.1042 + }
1.1043 +
1.1044 +
1.1045 +/**
1.1046 +Searches this descriptor's collated data for a match with the collated match
1.1047 +pattern supplied in the specified descriptor.
1.1048 +
1.1049 +The function uses the standard collation method appropriate to
1.1050 +the current locale.
1.1051 +
1.1052 +The match pattern can contain the wildcard characters specified by aWildChar and aWildSequenceChar
1.1053 +parameters, where aWildSequenceChar matches zero or more consecutive occurrences of any character and
1.1054 +aWildChar matches a single occurrence of any character.
1.1055 +
1.1056 +@param aPattern A 16-bit non-modifable descriptor containing the match pattern.
1.1057 +@param aFlags Flags providing advanced control of the collation algorithm @see TCollationFlag
1.1058 +@param aWildChar Wild card character which may be specified for aSearchTerm. Defaulted to '?' if omitted.
1.1059 +@param aWildSequenceChar Wild card sequence character which may be specified for aSearchTerm.
1.1060 + Defaulted to '*' if omitted.
1.1061 +@param aEscapeChar The escape character, or 0 if there is to be none. The escape character removes any
1.1062 + special meaning from the subsequent character. For example, if the escape, wild card
1.1063 + and wild sequence characters are \, ? And * respectively, the search term "\?\*\\" matches
1.1064 + only the candidate string "?*\". Defaulted to 0 if omitted.
1.1065 +@param aMaxLevel Determines the tightness of the collation. Defaulted to 3 if omitted. At level 0, only
1.1066 + character identities are distinguished. At level 1 accents are
1.1067 + distinguished as well. At level 2 case is distinguishes as well. At
1.1068 + level 3 all valid different Unicode characters are considered different.
1.1069 +@param aCollationMethod A pointer to the collation method. Collation methods can be retrieved by calls to
1.1070 + Mem::CollationMethodByIndex(), Mem::CollationMethodById() or by custom defined name.
1.1071 + Flags can be set on definition of the custom TCollationMethod, or by const_cast-ing
1.1072 + the returned pointer and setting the iFlags field directly. @see TCollationMethod
1.1073 +@return If a match is found, the offset within this descriptor's data where
1.1074 + the match first occurs. KErrNotFound, if there is no match.
1.1075 +*/
1.1076 +EXPORT_C TInt TDesC16::MatchC(const TDesC16 &aPattern, const TCollationMethod* aCollationMethod,
1.1077 + TInt aMaxLevel, TInt aWildChar, TInt aWildSequenceChar, TInt aEscapeChar) const
1.1078 + {
1.1079 + TCollate c(*aCollationMethod);
1.1080 + return c.Match(Ptr(), Length(), aPattern.Ptr(), aPattern.Length(), aMaxLevel, aWildChar, aWildSequenceChar, aEscapeChar);
1.1081 + }
1.1082 +
1.1083 +
1.1084 +#ifndef __DES16_MACHINE_CODED_HWORD__
1.1085 +EXPORT_C TInt TDesC16::Locate(TChar aChar) const
1.1086 +/**
1.1087 +Searches for the first occurrence of a character within this descriptor's
1.1088 +data.
1.1089 +
1.1090 +The search starts at the beginning of the data, i.e. at the leftmost
1.1091 +position.
1.1092 +
1.1093 +@param aChar The character to be found.
1.1094 +
1.1095 +@return The offset of the character position from the beginning of the data.
1.1096 + KErrNotFound, if no matching character can be found.
1.1097 +*/
1.1098 + {
1.1099 +
1.1100 + const TUint16 *pBuf=Ptr();
1.1101 + const TUint16 *pB=pBuf-1;
1.1102 + const TUint16 *pE=pB+Length();
1.1103 + do
1.1104 + {
1.1105 + if (pB==pE)
1.1106 + return KErrNotFound;
1.1107 + } while (TUint(*++pB)!=aChar);
1.1108 + return pB-pBuf;
1.1109 + }
1.1110 +#endif
1.1111 +
1.1112 +LOCAL_C TInt DoLocateF16(const TDesC16& aDes,TUint aChar)
1.1113 +//
1.1114 +// Locate character aChar in the descriptor folded.
1.1115 +//
1.1116 + {
1.1117 +#ifdef _UNICODE
1.1118 + const TText* table = convTable(EMatchFolded);
1.1119 + TUint16 aChar16 = (TUint16)aChar;
1.1120 + aChar = lookup(&aChar16,table);
1.1121 +#else
1.1122 + const TText* table=Locl::FoldTable;
1.1123 + if (aChar<0x100)
1.1124 + aChar=table[aChar];
1.1125 +#endif
1.1126 + const TUint16 *pBuf=aDes.Ptr();
1.1127 + const TUint16 *pB=pBuf-1;
1.1128 + const TUint16 *pE=pB+aDes.Length();
1.1129 + do
1.1130 + {
1.1131 + if (pB==pE)
1.1132 + return KErrNotFound;
1.1133 + } while (lookup(++pB,table)!=aChar);
1.1134 + return pB-pBuf;
1.1135 + }
1.1136 +
1.1137 +EXPORT_C TInt TDesC16::LocateF(TChar aChar) const
1.1138 +/**
1.1139 +Searches for the first occurrence of a folded character within this
1.1140 +descriptor's folded data.
1.1141 +
1.1142 +The search starts at the beginning of the data, i.e. at the leftmost
1.1143 +position.
1.1144 +
1.1145 +Note that folding is locale-independent behaviour. It is also important to
1.1146 +note that there can be no guarantee that folding is in any way culturally
1.1147 +appropriate, and should not be used for searching strings in natural language.
1.1148 +
1.1149 +@param aChar The character to be found.
1.1150 +
1.1151 +@return The offset of the character position from the beginning of the data.
1.1152 + KErrNotFound, if no matching character can be found.
1.1153 +*/
1.1154 + {
1.1155 +
1.1156 + return DoLocateF16(*this,aChar);
1.1157 +
1.1158 + }
1.1159 +
1.1160 +#ifndef __DES16_MACHINE_CODED_HWORD__
1.1161 +EXPORT_C TInt TDesC16::LocateReverse(TChar aChar) const
1.1162 +/**
1.1163 +Searches for the first occurrence of a character within this descriptor's
1.1164 +data, searching from the end of the data.
1.1165 +
1.1166 +The search starts at the rightmost position.
1.1167 +
1.1168 +@param aChar The character to be found.
1.1169 +
1.1170 +@return The offset of the character position from the beginning of the data.
1.1171 + KErrNotFound, if no matching character can be found.
1.1172 +*/
1.1173 + {
1.1174 +
1.1175 + TInt len=Length();
1.1176 + if (len==0)
1.1177 + return(KErrNotFound);
1.1178 + const TUint16 *pB=Ptr();
1.1179 + const TUint16 *pE=pB+len-1;
1.1180 + while (pE>=pB)
1.1181 + {
1.1182 + if (TUint(*pE)==aChar)
1.1183 + break;
1.1184 + pE--;
1.1185 + }
1.1186 + return(pE<pB ? KErrNotFound : pE-pB);
1.1187 + }
1.1188 +#endif
1.1189 +
1.1190 +EXPORT_C TInt TDesC16::LocateReverseF(TChar aChar) const
1.1191 +/**
1.1192 +Searches for the first occurrence of a folded character within this descriptor's
1.1193 +folded data, searching from the end of the data.
1.1194 +
1.1195 +The search starts at the rightmost position.
1.1196 +
1.1197 +Note that folding is locale-independent behaviour. It is also important to
1.1198 +note that there can be no guarantee that folding is in any way culturally
1.1199 +appropriate, and should not be used for searching strings in natural language.
1.1200 +
1.1201 +@param aChar The character to be found
1.1202 +@return The offset of the character position from the beginning of the data.
1.1203 + KErrNotFound, if no matching character can be found.
1.1204 +*/
1.1205 + {
1.1206 +
1.1207 + TInt len=Length();
1.1208 + if (len==0)
1.1209 + return(KErrNotFound);
1.1210 + const TUint16 *pB=Ptr();
1.1211 + const TUint16 *pE=pB+len-1;
1.1212 + aChar.Fold();
1.1213 + while (pE>=pB)
1.1214 + {
1.1215 + TCharF c(*pE);
1.1216 + if (c==aChar)
1.1217 + break;
1.1218 + pE--;
1.1219 + }
1.1220 + return(pE<pB ? KErrNotFound : pE-pB);
1.1221 + }
1.1222 +
1.1223 +EXPORT_C HBufC16 *TDesC16::Alloc() const
1.1224 +/**
1.1225 +Creates a new 16-bit heap descriptor and initialises it with a copy of this
1.1226 +descriptor's data.
1.1227 +
1.1228 +@return A pointer to the new 16-bit heap descriptor, if creation is successful.
1.1229 + NULL, if creation of the descriptor fails.
1.1230 +*/
1.1231 + {
1.1232 +
1.1233 + HBufC16 *pH=HBufC16::New(Length());
1.1234 + if (pH)
1.1235 + *pH=(*this);
1.1236 + return(pH);
1.1237 + }
1.1238 +
1.1239 +EXPORT_C HBufC16 *TDesC16::AllocL() const
1.1240 +/**
1.1241 +Creates a new 16-bit heap descriptor and initialises it with a copy of this
1.1242 +descriptor's data.
1.1243 +
1.1244 +The function leaves, if creation of the descriptor fails.
1.1245 +
1.1246 +@return A pointer to the 16-bit heap descriptor, if creation is successful.
1.1247 +*/
1.1248 + {
1.1249 +
1.1250 + HBufC16 *pH=HBufC16::NewL(Length());
1.1251 + *pH=(*this);
1.1252 + return(pH);
1.1253 + }
1.1254 +
1.1255 +EXPORT_C HBufC16 *TDesC16::AllocLC() const
1.1256 +/**
1.1257 +Creates a new 16-bit heap descriptor, initialises it with a copy of this
1.1258 +descriptor's data, and puts a pointer to the descriptor onto the cleanup stack.
1.1259 +
1.1260 +The function leaves, if creation of the descriptor fails.
1.1261 +
1.1262 +@return A pointer to the 16-bit heap descriptor, if creation is successful.
1.1263 + The pointer is also put onto the cleanup stack.
1.1264 +*/
1.1265 + {
1.1266 +
1.1267 + HBufC16 *pH=HBufC16::NewLC(Length());
1.1268 + *pH=(*this);
1.1269 + return(pH);
1.1270 + }
1.1271 +
1.1272 +#if !defined(__DES16_MACHINE_CODED__)
1.1273 +
1.1274 +EXPORT_C TPtrC16 TDesC16::Left(TInt aLength) const
1.1275 +/**
1.1276 +Extracts the leftmost part of the data.
1.1277 +
1.1278 +The function does not cut or remove any data but constructs a non-modifiable
1.1279 +pointer descriptor to represent the leftmost part of the data.
1.1280 +
1.1281 +@param aLength The length of the data to be extracted. If this value is
1.1282 + greater than the length of the descriptor, the function
1.1283 + extracts the whole of the descriptor.
1.1284 +
1.1285 +@return The 16-bit non-modifiable pointer descriptor representing the leftmost
1.1286 + part of the data.
1.1287 +
1.1288 +@panic USER 10 if aLength is negative.
1.1289 +*/
1.1290 + {
1.1291 +
1.1292 + __ASSERT_ALWAYS(aLength>=0,Panic(ETDes16PosOutOfRange));
1.1293 + return(TPtrC16(Ptr(),Min(aLength,Length())));
1.1294 + }
1.1295 +
1.1296 +EXPORT_C TPtrC16 TDesC16::Right(TInt aLength) const
1.1297 +/**
1.1298 +Extracts the rightmost part of the data.
1.1299 +
1.1300 +The function does not cut or remove any data but constructs a non-modifiable
1.1301 +pointer descriptor to represent the rightmost part of the data.
1.1302 +
1.1303 +@param aLength The length of data to be extracted. If this value
1.1304 + is greater than the length of the descriptor, the function
1.1305 + extracts the whole of the descriptor.
1.1306 +
1.1307 +@return The 16-bit non-modifiable pointer descriptor representing the rightmost
1.1308 + part of the data.
1.1309 +
1.1310 +@panic USER 10 if aLength is negative.
1.1311 +*/
1.1312 + {
1.1313 +
1.1314 + __ASSERT_ALWAYS(aLength>=0,Panic(ETDes16PosOutOfRange));
1.1315 + TInt len=Length();
1.1316 + if (aLength>len)
1.1317 + aLength=len;
1.1318 + return(TPtrC16(Ptr()+len-aLength,aLength));
1.1319 + }
1.1320 +
1.1321 +EXPORT_C TPtrC16 TDesC16::Mid(TInt aPos) const
1.1322 +/**
1.1323 +Extracts a portion of the data.
1.1324 +
1.1325 +The function does not cut or remove any data but constructs a non-modifiable
1.1326 +pointer descriptor to represent the defined portion.
1.1327 +
1.1328 +The portion is identified by its starting position and by the length of the
1.1329 +remainder of the data starting from the specified position.
1.1330 +
1.1331 +@param aPos The starting position of the data to be extracted. This is an
1.1332 + offset value; a zero value refers to the leftmost data position.
1.1333 +
1.1334 +@return The 16-bit non-modifiable pointer descriptor representing the specified
1.1335 + portion of the data.
1.1336 +
1.1337 +@panic USER 10 if aPos is negative or aPos is greater than the
1.1338 + length of the descriptor.
1.1339 +*/
1.1340 + {
1.1341 +
1.1342 + TInt len=Length();
1.1343 + __ASSERT_ALWAYS(aPos>=0 && aPos<=len,Panic(ETDes16PosOutOfRange));
1.1344 + return(TPtrC16(Ptr()+aPos,len-aPos));
1.1345 + }
1.1346 +
1.1347 +EXPORT_C TPtrC16 TDesC16::Mid(TInt aPos,TInt aLength) const
1.1348 +/**
1.1349 +Extracts a portion of the data.
1.1350 +
1.1351 +The function does not cut or remove any data but constructs a non-modifiable
1.1352 +pointer descriptor to represent the defined portion.
1.1353 +
1.1354 +The portion is identified by its starting position and by its length.
1.1355 +
1.1356 +@param aPos The starting position of the data to be extracted. This is an
1.1357 + offset value; a zero value refers to the leftmost data position.
1.1358 +@param aLength The length of data to be extracted.
1.1359 +
1.1360 +@return The 16-bit non-modifiable pointer descriptor representing the specified
1.1361 + portion of the data.
1.1362 +
1.1363 +@panic USER 10 if aPos is negative or aPos plus aLength is greater than the
1.1364 + length of the descriptor.
1.1365 +*/
1.1366 + {
1.1367 +
1.1368 + __ASSERT_ALWAYS(aPos>=0 && (aPos+aLength)<=Length(),Panic(ETDes16PosOutOfRange));
1.1369 + return(TPtrC16(Ptr()+aPos,aLength));
1.1370 + }
1.1371 +
1.1372 +#endif // !defined(__DES16_MACHINE_CODED__)
1.1373 +
1.1374 +#if !defined( __DES16_MACHINE_CODED__) | defined(__EABI_CTORS__)
1.1375 +EXPORT_C TBufCBase16::TBufCBase16()
1.1376 +//
1.1377 +// Constructor
1.1378 +//
1.1379 + : TDesC16(EBufC,0)
1.1380 + {}
1.1381 +#endif
1.1382 +
1.1383 +#if !defined( __DES16_MACHINE_CODED_HWORD__) | defined(__EABI_CTORS__)
1.1384 +EXPORT_C TBufCBase16::TBufCBase16(const TUint16 *aString,TInt aMaxLength)
1.1385 +//
1.1386 +// Constructor
1.1387 +//
1.1388 + : TDesC16(EBufC,0)
1.1389 + {
1.1390 + Copy(aString,aMaxLength);
1.1391 + }
1.1392 +#endif
1.1393 +
1.1394 +#if !defined( __DES16_MACHINE_CODED__) | defined(__EABI_CTORS__)
1.1395 +EXPORT_C TBufCBase16::TBufCBase16(const TDesC16 &aDes,TInt aMaxLength)
1.1396 +//
1.1397 +// Constructor
1.1398 +//
1.1399 + : TDesC16(EBufC,0)
1.1400 + {
1.1401 + Copy(aDes,aMaxLength);
1.1402 + }
1.1403 +#endif
1.1404 +
1.1405 +#ifndef __DES16_MACHINE_CODED_HWORD__
1.1406 +EXPORT_C void TBufCBase16::Copy(const TUint16 *aString,TInt aMaxLength)
1.1407 +//
1.1408 +// Copy from a string.
1.1409 +//
1.1410 + {
1.1411 +
1.1412 + __CHECK_ALIGNMENT(aString,ETBufCBase16CopyStringMax);
1.1413 + TInt len=STRING_LENGTH_16(aString);
1.1414 + __ASSERT_ALWAYS(len<=aMaxLength,Panic(ETDes16Overflow));
1.1415 + memCopy(WPtr(),aString,len);
1.1416 + DoSetLength(len);
1.1417 + }
1.1418 +#endif
1.1419 +
1.1420 +#ifndef __DES16_MACHINE_CODED__
1.1421 +EXPORT_C void TBufCBase16::Copy(const TDesC16 &aDes,TInt aMaxLength)
1.1422 +//
1.1423 +// Copy from a descriptor.
1.1424 +//
1.1425 + {
1.1426 +
1.1427 + TInt len=aDes.Length();
1.1428 + __ASSERT_ALWAYS(len<=aMaxLength,Panic(ETDes16Overflow));
1.1429 + memCopy(WPtr(),aDes.Ptr(),len);
1.1430 + DoSetLength(len);
1.1431 + }
1.1432 +#endif
1.1433 +
1.1434 +inline HBufC16::HBufC16(TInt aLength)
1.1435 + :TBufCBase16(aLength)
1.1436 + {}
1.1437 +
1.1438 +EXPORT_C HBufC16 *HBufC16::New(TInt aMaxLength)
1.1439 +/**
1.1440 +Creates, and returns a pointer to, a new 16-bit heap descriptor.
1.1441 +
1.1442 +The heap descriptor is empty and its length is zero.
1.1443 +
1.1444 +Data can, subsequently, be assigned into it using the assignment operators.
1.1445 +
1.1446 +@param aMaxLength The requested maximum length of the descriptor. Note that
1.1447 + the resulting heap cell size and, therefore, the resulting
1.1448 + maximum length of the descriptor may be larger than
1.1449 + requested.
1.1450 +
1.1451 +@return A pointer to the new 16-bit heap descriptor. NULL, if the 16-bit heap
1.1452 + descriptor cannot be created.
1.1453 +
1.1454 +@panic USER 18 if aMaxLength is negative.
1.1455 +
1.1456 +@see HBufC16::operator=()
1.1457 +*/
1.1458 + {
1.1459 + __ASSERT_ALWAYS(aMaxLength>=0,Panic(ETDes16MaxLengthNegative));
1.1460 + return new(STD_CLASS::Alloc(_FOFF(HBufC16,iBuf[aMaxLength]))) HBufC16(0);
1.1461 + }
1.1462 +
1.1463 +EXPORT_C HBufC16 *HBufC16::NewL(TInt aMaxLength)
1.1464 +/**
1.1465 +Creates, and returns a pointer to, a new 16-bit heap descriptor, and leaves
1.1466 +on failure.
1.1467 +
1.1468 +The heap descriptor is empty and its length is zero.
1.1469 +
1.1470 +Data can, subsequently, be assigned into it using the assignment operators.
1.1471 +
1.1472 +@param aMaxLength The requested maximum length of the descriptor. Note that
1.1473 + the resulting heap cell size and, therefore, the resulting
1.1474 + maximum length of the descriptor may be larger
1.1475 + than requested.
1.1476 +
1.1477 +@return A pointer to the new 16-bit heap descriptor. The function leaves, if
1.1478 + the new 16-bit heap descriptor cannot be created.
1.1479 +
1.1480 +
1.1481 +@panic USER 18 if aMaxLength is negative.
1.1482 +
1.1483 +@see HBufC16::operator=()
1.1484 +*/
1.1485 + {
1.1486 + return static_cast<HBufC16*>(User::LeaveIfNull(New(aMaxLength)));
1.1487 + }
1.1488 +
1.1489 +EXPORT_C HBufC16 *HBufC16::NewLC(TInt aMaxLength)
1.1490 +/**
1.1491 +Creates, adds a pointer onto the cleanup stack and returns a pointer to, a
1.1492 +new 16-bit heap descriptor; leaves on failure.
1.1493 +
1.1494 +The heap descriptor is empty and its length is zero.
1.1495 +
1.1496 +Data can, subsequently, be assigned into it using the assignment operators.
1.1497 +
1.1498 +@param aMaxLength The requested maximum length of the descriptor. Note that
1.1499 + the resulting heap cell size and, therefore, the resulting
1.1500 + maximum length of the descriptor may be larger
1.1501 + than requested.
1.1502 +
1.1503 +@return A pointer to the new 16-bit heap descriptor. The function leaves, if
1.1504 + the new 16-bit heap descriptor cannot be created.
1.1505 +
1.1506 +@panic USER 18 if aMaxLength is negative.
1.1507 +
1.1508 +@see HBufC16::operator=()
1.1509 +*/
1.1510 + {
1.1511 + HBufC16* buf=NewL(aMaxLength);
1.1512 + CleanupStack::PushL(buf);
1.1513 + return buf;
1.1514 + }
1.1515 +
1.1516 +EXPORT_C HBufC16 *HBufC16::NewMax(TInt aMaxLength)
1.1517 +/**
1.1518 +Creates, and returns a pointer to, a new 16-bit heap descriptor.
1.1519 +
1.1520 +No data is assigned into the new descriptor but its length
1.1521 +is set to aMaxLength.
1.1522 +
1.1523 +Data can, subsequently, be assigned into it using the assignment operators.
1.1524 +
1.1525 +@param aMaxLength The requested maximum length of the descriptor. Note that
1.1526 + the resulting heap cell size and, therefore, the resulting
1.1527 + maximum length of the descriptor may be larger
1.1528 + than requested. This also means that the resulting maximum
1.1529 + length of the descriptor may be greater than its length.
1.1530 +@return A pointer to the new 16-bit heap descriptor. NULL, if the new 16-bit
1.1531 + heap descriptor cannot be created.
1.1532 +
1.1533 +@panic USER 18 if aMaxLength is negative.
1.1534 +
1.1535 +@see HBufC16::operator=()
1.1536 +*/
1.1537 + {
1.1538 + __ASSERT_ALWAYS(aMaxLength>=0,Panic(ETDes16MaxLengthNegative));
1.1539 + return new(STD_CLASS::Alloc(_FOFF(HBufC16,iBuf[aMaxLength]))) HBufC16(aMaxLength);
1.1540 + }
1.1541 +
1.1542 +EXPORT_C HBufC16 *HBufC16::NewMaxL(TInt aMaxLength)
1.1543 +/**
1.1544 +Creates, and returns a pointer to, a new 16-bit heap descriptor;
1.1545 +leaves on failure.
1.1546 +
1.1547 +No data is assigned into the new descriptor but its length is set
1.1548 +to aMaxLength.
1.1549 +
1.1550 +Data can, subsequently, be assigned into it using the assignment operators.
1.1551 +
1.1552 +@param aMaxLength The requested maximum length of the descriptor. Note that
1.1553 + the resulting heap cell size and, therefore, the resulting
1.1554 + maximum length of the descriptor may be larger
1.1555 + than requested. This also means that the resulting
1.1556 + maximum length of the descriptor may be greater than its length.
1.1557 +
1.1558 +@return A pointer to the new 16-bit heap descriptor. The function leaves, if
1.1559 + the new 16-bit heap descriptor cannot be created.
1.1560 +
1.1561 +@panic USER 18 if aMaxLength is negative.
1.1562 +
1.1563 +@see HBufC16::operator=()
1.1564 +*/
1.1565 + {
1.1566 + return static_cast<HBufC16*>(User::LeaveIfNull(NewMax(aMaxLength)));
1.1567 + }
1.1568 +
1.1569 +EXPORT_C HBufC16 *HBufC16::NewMaxLC(TInt aMaxLength)
1.1570 +/**
1.1571 +Creates, adds a pointer onto the cleanup stack and returns a pointer to, a
1.1572 +new 16-bit heap descriptor; leaves on failure.
1.1573 +
1.1574 +No data is assigned into the new descriptor but its length
1.1575 +is set to aMaxLength.
1.1576 +
1.1577 +Data can, subsequently, be assigned into it using the assignment operators.
1.1578 +
1.1579 +@param aMaxLength The requested maximum length of the descriptor. Note that
1.1580 + the resulting heap cell size and, therefore, the resulting
1.1581 + maximum length of the descriptor may be larger than requested.
1.1582 +
1.1583 +@return A pointer to the new 16-bit heap descriptor. This is also put onto
1.1584 + the cleanup stack. The function leaves, if the new 16-bit heap descriptor
1.1585 + cannot be created.
1.1586 +
1.1587 +@panic USER 18 if aMaxLength is negative.
1.1588 +
1.1589 +@see HBufC16::operator=()
1.1590 +*/
1.1591 + {
1.1592 + HBufC16* buf=NewMaxL(aMaxLength);
1.1593 + CleanupStack::PushL(buf);
1.1594 + return buf;
1.1595 + }
1.1596 +
1.1597 +EXPORT_C HBufC16 &HBufC16::operator=(const TUint16 *aString)
1.1598 +/**
1.1599 +Copies data into this 16-bit heap descriptor replacing any existing data.
1.1600 +
1.1601 +The length of this descriptor is set to reflect the new data.
1.1602 +
1.1603 +Note that the maximum length of this (target) descriptor is the length
1.1604 +of the descriptor buffer in the allocated host heap cell; this may be greater
1.1605 +than the maximum length specified when this descriptor was created or
1.1606 +last re-allocated.
1.1607 +
1.1608 +@param aString A pointer to a zero-terminated string.
1.1609 +
1.1610 +@return A reference to this 16-bit heap descriptor.
1.1611 +
1.1612 +@panic USER 11 if the length of the string, excluding the zero terminator,
1.1613 + is greater than the maximum length of this (target) descriptor.
1.1614 +*/
1.1615 + {
1.1616 +
1.1617 + __CHECK_ALIGNMENT(aString,EHBufC16AssignCString);
1.1618 + Copy(aString,(STD_CLASS::AllocLen(this)-sizeof(TDesC16))/sizeof(TUint16));
1.1619 + return(*this);
1.1620 + }
1.1621 +
1.1622 +EXPORT_C HBufC16 &HBufC16::operator=(const TDesC16 &aDes)
1.1623 +/**
1.1624 +Copies data into this 16-bit heap descriptor replacing any existing data.
1.1625 +
1.1626 +The length of this descriptor is set to reflect the new data.
1.1627 +
1.1628 +Note that the maximum length of this (target) descriptor is the length
1.1629 +of the descriptor buffer in the allocated host heap cell; this may be greater
1.1630 +than the maximum length specified when this descriptor was created or
1.1631 +last re-allocated.
1.1632 +
1.1633 +@param aDes A 16-bit non-modifiable descriptor.
1.1634 +
1.1635 +@return A reference to this 16-bit heap descriptor.
1.1636 +
1.1637 +@panic USER 11 if the length of the descriptor aDes is greater than the
1.1638 + maximum length of this (target) descriptor
1.1639 +*/
1.1640 + {
1.1641 +
1.1642 + Copy(aDes,(STD_CLASS::AllocLen(this)-sizeof(TDesC16))/sizeof(TUint16));
1.1643 + return(*this);
1.1644 + }
1.1645 +
1.1646 +EXPORT_C HBufC16 *HBufC16::ReAlloc(TInt aMaxLength)
1.1647 +/**
1.1648 +Expands or contracts this 16-bit heap descriptor.
1.1649 +
1.1650 +This is done by:
1.1651 +
1.1652 +1. creating a new heap descriptor.
1.1653 +
1.1654 +2. copying the original data into the new descriptor.
1.1655 +
1.1656 +3. deleting the original descriptor.
1.1657 +
1.1658 +@param aMaxLength The new requested maximum length of the descriptor.
1.1659 + Note that the resulting heap cell size and, therefore,
1.1660 + the resulting maximum length of the descriptor may be
1.1661 + larger than requested.
1.1662 +
1.1663 +@return A pointer to the new expanded or contracted 16-bit heap descriptor -
1.1664 + the original descriptor is deleted. NULL, if the new 16-bit heap descriptor
1.1665 + cannot be created - the original descriptor remains unchanged.
1.1666 +
1.1667 +@panic USER 14 if aMaxLength is less than the length of the existing data.
1.1668 +@panic USER 18 if aMaxLength is negative.
1.1669 +*/
1.1670 + {
1.1671 +
1.1672 + __ASSERT_ALWAYS(aMaxLength>=0,Panic(ETDes16MaxLengthNegative));
1.1673 + __ASSERT_ALWAYS(Length()<=aMaxLength,Panic(ETDes16ReAllocTooSmall));
1.1674 + return((HBufC16 *)STD_CLASS::ReAlloc(this,(aMaxLength*sizeof(TUint16))+sizeof(TDesC16)));
1.1675 + }
1.1676 +
1.1677 +EXPORT_C HBufC16 *HBufC16::ReAllocL(TInt aMaxLength)
1.1678 +/**
1.1679 +Expands or contracts this 16-bit heap descriptor; leaves on failure.
1.1680 +
1.1681 +This is done by:
1.1682 +
1.1683 +1. creating a new heap descriptor.
1.1684 +
1.1685 +2. copying the original data into the new descriptor.
1.1686 +
1.1687 +3. deleting the original descriptor.
1.1688 +
1.1689 +@param aMaxLength The new requested maximum length of the descriptor.
1.1690 + Note that the resulting heap cell size and, therefore,
1.1691 + the resulting maximum length of the descriptor may be
1.1692 + larger than requested.
1.1693 +
1.1694 +@return A pointer to the new expanded or contracted 16-bit heap descriptor -
1.1695 + the original descriptor is deleted. The function leaves, if the new
1.1696 + 16-bit heap descriptor cannot be created - the original descriptor
1.1697 + remains unchanged.
1.1698 +
1.1699 +@panic USER 14 if aMaxLength is less than the length of the existing data.
1.1700 +@panic USER 18 if aMaxLength is negative.
1.1701 +*/
1.1702 + {
1.1703 +
1.1704 + __ASSERT_ALWAYS(aMaxLength>=0,Panic(ETDes16MaxLengthNegative));
1.1705 + __ASSERT_ALWAYS(Length()<=aMaxLength,Panic(ETDes16ReAllocTooSmall));
1.1706 + return((HBufC16 *)STD_CLASS::ReAllocL(this,(aMaxLength*sizeof(TUint16))+sizeof(TDesC16)));
1.1707 + }
1.1708 +
1.1709 +EXPORT_C TPtr16 HBufC16::Des()
1.1710 +/**
1.1711 +Creates and returns a 16-bit modifiable pointer descriptor for the data
1.1712 +represented by this 16-bit heap descriptor.
1.1713 +
1.1714 +The content of a heap descriptor normally cannot be altered, other than by
1.1715 +complete replacement of the data. Creating a modifiable pointer descriptor
1.1716 +provides a way of changing the data.
1.1717 +
1.1718 +The modifiable pointer descriptor is set to point to this heap descriptor's
1.1719 +data.
1.1720 +
1.1721 +The length of the modifiable pointer descriptor is set to the length of this
1.1722 +heap descriptor.
1.1723 +
1.1724 +The maximum length of the modifiable pointer descriptor is set to the length
1.1725 +of the heap descriptor's buffer. Note that the maximum length is the length
1.1726 +of the descriptor buffer in the allocated host heap cell; this may be greater
1.1727 +than the maximum length requested when this descriptor was originally created
1.1728 +or last re-allocated.
1.1729 +
1.1730 +When data is modified through this new pointer descriptor, the lengths of
1.1731 +both it and this heap descriptor are changed.
1.1732 +
1.1733 +Note that it is a common mistake to use Des() to create a TDesC16& reference.
1.1734 +While not incorrect, it is simpler and much more efficient to simply dereference
1.1735 +the heap descriptor.
1.1736 +
1.1737 +@return A 16-bit modifiable pointer descriptor representing the data in this
1.1738 + 16-bit heap descriptor.
1.1739 +*/
1.1740 + {
1.1741 +
1.1742 + return DoDes((STD_CLASS::AllocLen(this)-sizeof(TDesC16))/sizeof(TUint16));
1.1743 + }
1.1744 +
1.1745 +#ifndef __DES16_MACHINE_CODED__
1.1746 +EXPORT_C void TDes16::SetLength(TInt aLength)
1.1747 +/**
1.1748 +Sets the length of the data represented by the descriptor to the
1.1749 +specified value.
1.1750 +
1.1751 +@param aLength The new length of the descriptor.
1.1752 +
1.1753 +@panic USER 11 if aLength is negative or is greater than the maximum length of
1.1754 + this (target) descriptor.
1.1755 +*/
1.1756 + {
1.1757 +
1.1758 + __ASSERT_ALWAYS(TUint(aLength)<=TUint(MaxLength()),Panic(ETDes16Overflow));
1.1759 + DoSetLength(aLength);
1.1760 + if (Type()==EBufCPtr)
1.1761 + ((SBufCPtr16 *)this)->ptr->length=aLength; // Relies on iType==0 for an TBufC
1.1762 + }
1.1763 +
1.1764 +EXPORT_C void TDes16::SetMax()
1.1765 +/**
1.1766 +Sets the length of the data to the maximum length of the descriptor.
1.1767 +*/
1.1768 + {
1.1769 +
1.1770 + SetLength(iMaxLength);
1.1771 + }
1.1772 +#endif
1.1773 +
1.1774 +#ifndef __DES16_MACHINE_CODED_HWORD__
1.1775 +EXPORT_C void TDes16::Copy(const TUint16 *aString)
1.1776 +/**
1.1777 +Copies data into this descriptor replacing any existing data.
1.1778 +
1.1779 +The length of this descriptor is set to reflect the new data.
1.1780 +
1.1781 +@param aString A pointer to a zero-terminated string.
1.1782 +
1.1783 +@panic USER 11 if the length of aString, excluding the zero terminator, is
1.1784 + greater than the maximum length of this (target) descriptor.
1.1785 +*/
1.1786 + {
1.1787 +
1.1788 + __CHECK_ALIGNMENT(aString,ETDes16CopyCString);
1.1789 + TInt len=STRING_LENGTH_16(aString);
1.1790 + SetLength(len);
1.1791 + memCopy(WPtr(),aString,len);
1.1792 + }
1.1793 +#endif
1.1794 +
1.1795 +#ifndef __DES16_MACHINE_CODED__
1.1796 +EXPORT_C void TDes16::Copy(const TUint16 *aBuf,TInt aLength)
1.1797 +/**
1.1798 +Copies data into this descriptor replacing any existing data.
1.1799 +
1.1800 +The length of this descriptor is set to reflect the new data.
1.1801 +
1.1802 +@param aBuf The start address of data to be copied.
1.1803 +@param aLength The length of data to be copied.
1.1804 +
1.1805 +@panic USER 11 if aLength is negative or is greater than maximum length
1.1806 + of this (target) descriptor.
1.1807 +*/
1.1808 + {
1.1809 +
1.1810 + __CHECK_ALIGNMENT(aBuf,ETDes16CopyBufLength);
1.1811 + SetLength(aLength);
1.1812 + memCopy(WPtr(),aBuf,aLength);
1.1813 + }
1.1814 +
1.1815 +EXPORT_C void TDes16::Copy(const TDesC16 &aDes)
1.1816 +/**
1.1817 +Copies data into this descriptor replacing any existing data.
1.1818 +
1.1819 +The length of this descriptor is set to reflect the new data.
1.1820 +
1.1821 +@param aDes A 16-bit non modifiable descriptor.
1.1822 +
1.1823 +@panic USER 11 if the length of aDes is greater than the maximum length
1.1824 + of this (target) descriptor.
1.1825 +*/
1.1826 + {
1.1827 +
1.1828 + TInt len=aDes.Length();
1.1829 + SetLength(len);
1.1830 + memCopy(WPtr(),aDes.Ptr(),len);
1.1831 + }
1.1832 +#endif
1.1833 +
1.1834 +EXPORT_C void TDes16::Copy(const TDesC8 &aDes)
1.1835 +/**
1.1836 +Copies data into this descriptor replacing any existing data.
1.1837 +
1.1838 +The length of this descriptor is set to reflect the new data.
1.1839 +
1.1840 +@param aDes An 8 bit non modifiable descriptor.
1.1841 +
1.1842 +@panic USER 11 if the length of aDes is greater than the maximum
1.1843 + length of this (target) descriptor.
1.1844 +*/
1.1845 + {
1.1846 +
1.1847 + TInt len=aDes.Length();
1.1848 + SetLength(len);
1.1849 + const TUint8 *pS=aDes.Ptr();
1.1850 + const TUint8 *pE=pS+len;
1.1851 + TUint16 *pT=WPtr();
1.1852 + while (pS<pE)
1.1853 + *pT++=(*pS++);
1.1854 + }
1.1855 +
1.1856 +#ifndef __DES16_MACHINE_CODED_HWORD__
1.1857 +EXPORT_C void TDes16::Append(TChar aChar)
1.1858 +/**
1.1859 +Appends data onto the end of this descriptor's data.
1.1860 +
1.1861 +The length of this descriptor is incremented to reflect the new content.
1.1862 +
1.1863 +@param aChar A single character to be appended. The length of the descriptor
1.1864 + is incremented by one.
1.1865 +
1.1866 +@panic USER 11 if the resulting new length of this descriptor is greater than
1.1867 + its maximum length.
1.1868 +*/
1.1869 + {
1.1870 +
1.1871 + TInt len=Length();
1.1872 + TUint16 *pB=WPtr()+len;
1.1873 + SetLength(len+1);
1.1874 + *pB++=(TUint16)aChar;
1.1875 + }
1.1876 +#endif
1.1877 +
1.1878 +#ifndef __DES16_MACHINE_CODED__
1.1879 +EXPORT_C void TDes16::Append(const TUint16 *aBuf,TInt aLength)
1.1880 +/**
1.1881 +Appends data onto the end of this descriptor's data.
1.1882 +
1.1883 +The length of this descriptor is incremented to reflect the new content.
1.1884 +
1.1885 +@param aBuf A pointer to the data to be copied.
1.1886 +@param aLength The length of data to be copied.
1.1887 +
1.1888 +@panic USER 11 if the resulting new length of this descriptor is greater than
1.1889 + its maximum length.
1.1890 +@panic USER 17 if aLength is negative.
1.1891 +*/
1.1892 + {
1.1893 +
1.1894 + __ASSERT_ALWAYS(aLength>=0,Panic(ETDes16LengthNegative));
1.1895 + __CHECK_ALIGNMENT(aBuf,ETDes16AppendBufLength);
1.1896 + TInt len=Length();
1.1897 + SetLength(len+aLength);
1.1898 + memCopy(WPtr()+len,aBuf,aLength);
1.1899 + }
1.1900 +
1.1901 +EXPORT_C void TDes16::Append(const TDesC16 &aDes)
1.1902 +/**
1.1903 +Appends data onto the end of this descriptor's data.
1.1904 +
1.1905 +The length of this descriptor is incremented to reflect the new content.
1.1906 +
1.1907 +@param aDes A 16-bit non modifiable descriptor whose data is to be appended.
1.1908 +
1.1909 +@panic USER 11 if the resulting new length of this descriptor is greater than
1.1910 + its maximum length.
1.1911 +*/
1.1912 + {
1.1913 +
1.1914 + TInt len=Length();
1.1915 + TInt n=aDes.Length();
1.1916 + SetLength(len+n);
1.1917 + memCopy(WPtr()+len,aDes.Ptr(),n);
1.1918 + }
1.1919 +#endif
1.1920 +
1.1921 +EXPORT_C void TDes16::Swap(TDes16 &aDes)
1.1922 +/**
1.1923 +Swaps the data represented by this descriptor with the data represented by
1.1924 +the specified descriptor.
1.1925 +
1.1926 +The lengths of both descriptors are also swapped to reflect the change.
1.1927 +
1.1928 +Note that each descriptor must be capable of accommodating the contents of
1.1929 +the other descriptor.
1.1930 +
1.1931 +Each descriptor must be capable of accommodating the contents of the other
1.1932 +descriptor. If the maximum length of either descriptor is smaller than the
1.1933 +length of the other descriptor, then the function raises a USER 11 panic.
1.1934 +
1.1935 +@param aDes The 16-bit modifiable descriptor whose data is to be swapped with
1.1936 + the data of this descriptor.
1.1937 +
1.1938 +@panic USER 11 if the maximum length of either descriptor is smaller than the
1.1939 + length of the other descriptor.
1.1940 +*/
1.1941 + {
1.1942 +
1.1943 + TInt l=Length();
1.1944 + TInt r=aDes.Length();
1.1945 + aDes.SetLength(l);
1.1946 + SetLength(r);
1.1947 + TInt s=Min(l,r);
1.1948 + l-=s;
1.1949 + r-=s;
1.1950 + TUint16 *pL=WPtr();
1.1951 + TUint16 *pR=aDes.WPtr();
1.1952 + while (s--)
1.1953 + {
1.1954 + TChar a=(*pL);
1.1955 + *pL++=(*pR);
1.1956 + *pR++=(TUint16)a;
1.1957 + }
1.1958 + while (l--)
1.1959 + *pR++=(*pL++);
1.1960 + while (r--)
1.1961 + *pL++=(*pR++);
1.1962 + }
1.1963 +
1.1964 +#ifndef __DES16_MACHINE_CODED_HWORD__
1.1965 +EXPORT_C void TDes16::Fill(TChar aChar)
1.1966 +/**
1.1967 +Fills the descriptor's data area with the specified character, replacing any
1.1968 +existing data.
1.1969 +
1.1970 +The descriptor is filled from the beginning up to its current length. The
1.1971 +descriptor's length does not change. It is not filled to its maximum length.
1.1972 +
1.1973 +@param aChar The fill character.
1.1974 +*/
1.1975 + {
1.1976 +
1.1977 + TUint16 *pB=WPtr();
1.1978 + TUint16 *pE=pB+Length();
1.1979 + while (pB<pE)
1.1980 + *pB++=(TUint16)aChar;
1.1981 + }
1.1982 +#endif
1.1983 +
1.1984 +EXPORT_C void TDes16::Fill(TChar aChar,TInt aLength)
1.1985 +/**
1.1986 +Fills the descriptor's data area with the specified character, replacing any
1.1987 +existing data.
1.1988 +
1.1989 +The descriptor is filled with the specified number of characters,
1.1990 +and its length is changed to reflect this.
1.1991 +
1.1992 +@param aChar The fill character.
1.1993 +@param aLength The new length of the descriptor and the number of fill characters
1.1994 + to be copied into it.
1.1995 +
1.1996 +@panic USER 11 if aLength is negative or is greater than the maximum length
1.1997 + of this descriptor.
1.1998 +*/
1.1999 + {
1.2000 +
1.2001 + SetLength(aLength);
1.2002 + Fill(aChar);
1.2003 + }
1.2004 +
1.2005 +EXPORT_C void TDes16::AppendFill(TChar aChar,TInt aLength)
1.2006 +/**
1.2007 +Appends and fills this descriptor with the specified character.
1.2008 +
1.2009 +The descriptor is appended with the specified number of characters.
1.2010 +and its length is changed to reflect this.
1.2011 +
1.2012 +@param aChar The fill character.
1.2013 +@param aLength The number of fill characters to be appended.
1.2014 +
1.2015 +@panic USER 11 if aLength is negative, or the resulting length of this
1.2016 + descriptor is greater than its maximum length.
1.2017 +*/
1.2018 + {
1.2019 +
1.2020 + TInt len=Length();
1.2021 + TUint16 *pB=WPtr()+len;
1.2022 + SetLength(len+aLength);
1.2023 + TUint16 *pE=pB+aLength;
1.2024 + while (pB<pE)
1.2025 + *pB++=(TUint16)aChar;
1.2026 + }
1.2027 +
1.2028 +#ifndef __DES16_MACHINE_CODED_HWORD__
1.2029 +EXPORT_C void TDes16::ZeroTerminate()
1.2030 +/**
1.2031 +Appends a zero terminator onto the end of this descriptor's data.
1.2032 +
1.2033 +The length of the descriptor is not changed. It must, however, be strictly less than
1.2034 +the descriptor's maximum length.
1.2035 +This condition guarantees that there is sufficient space for the zero terminator.
1.2036 +
1.2037 +@panic USER 11 if the descriptor's length is not strictly less than its
1.2038 + maximum length.
1.2039 +*/
1.2040 + {
1.2041 +
1.2042 + TInt len=Length();
1.2043 + __ASSERT_ALWAYS(len<MaxLength(),Panic(ETDes16Overflow));
1.2044 + WPtr()[len]=0;
1.2045 + }
1.2046 +
1.2047 +EXPORT_C const TUint16 *TDes16::PtrZ()
1.2048 +/**
1.2049 +Appends a zero terminator onto the end of this descriptor's data and returns
1.2050 +a pointer to the data.
1.2051 +
1.2052 +The length of the descriptor is not changed. It must be strictly less than
1.2053 +the descriptor's maximum length.
1.2054 +This condition guarantees that there is sufficient space for the
1.2055 +zero terminator.
1.2056 +
1.2057 +@return A pointer to the descriptor's zero terminated data.
1.2058 +
1.2059 +@panic USER 11 if the descriptor's length is not strictly less than its
1.2060 + maximum length.
1.2061 +*/
1.2062 + {
1.2063 +
1.2064 + ZeroTerminate();
1.2065 + return(Ptr());
1.2066 + }
1.2067 +#endif
1.2068 +
1.2069 +#ifndef __DES16_MACHINE_CODED__
1.2070 +EXPORT_C void TDes16::Zero()
1.2071 +/**
1.2072 +Sets the length of the data to zero.
1.2073 +*/
1.2074 + {
1.2075 +
1.2076 + SetLength(0);
1.2077 + }
1.2078 +#endif
1.2079 +
1.2080 +#ifndef __DES16_MACHINE_CODED__
1.2081 +EXPORT_C void TDes16::FillZ()
1.2082 +/**
1.2083 +Fills the descriptor's data area with binary zeroes, i.e.0x0000, replacing any
1.2084 +existing data.
1.2085 +
1.2086 +The descriptor is filled from the beginning up to its current length. The
1.2087 +descriptor's length does not change. It is not filled to its maximum length.
1.2088 +*/
1.2089 + {
1.2090 +
1.2091 + memclr(WPtr(),Length()*2);
1.2092 + }
1.2093 +#endif
1.2094 +
1.2095 +EXPORT_C void TDes16::FillZ(TInt aLength)
1.2096 +/**
1.2097 +Fills the descriptor's data area with binary zeroes, i.e. 0x0000, replacing any
1.2098 +existing data, and changes its length.
1.2099 +
1.2100 +The descriptor is filled with the specified number of binary zeroes.
1.2101 +The descriptor's length is changed to reflect this.
1.2102 +
1.2103 +@param aLength The new length of the descriptor and the number of binary zeroes
1.2104 + to be copied into it.
1.2105 +
1.2106 +@panic USER 11 if aLength is negative, or is greater than the maximum length
1.2107 + of this descriptor.
1.2108 +*/
1.2109 + {
1.2110 +
1.2111 + SetLength(aLength);
1.2112 + FillZ();
1.2113 + }
1.2114 +
1.2115 +EXPORT_C void TDes16::Fold()
1.2116 +/**
1.2117 +Performs folding on the content of this descriptor.
1.2118 +
1.2119 +Note that folding is locale-independent behaviour. It is also important to
1.2120 +note that there can be no guarantee that folding is in any way culturally
1.2121 +appropriate, and should not be used when dealing with strings in natural
1.2122 +language.
1.2123 +*/
1.2124 + {
1.2125 +
1.2126 + TUint16 *pB=WPtr();
1.2127 + TInt len=Length();
1.2128 + while (len--)
1.2129 + {
1.2130 + TCharF c(*pB);
1.2131 + *pB++=(TUint16)c;
1.2132 + }
1.2133 + }
1.2134 +
1.2135 +EXPORT_C void TDes16::Collate()
1.2136 +/**
1.2137 +Performs collation on the content of this descriptor.
1.2138 +*/
1.2139 + {
1.2140 +
1.2141 + TUint16 *pB=WPtr();
1.2142 + TInt len=Length();
1.2143 + while (len--)
1.2144 + {
1.2145 + TChar c=User::Collate(*pB);
1.2146 + *pB++=(TUint16)c;
1.2147 + }
1.2148 + }
1.2149 +
1.2150 +EXPORT_C void TDes16::LowerCase()
1.2151 +/**
1.2152 +Converts the content of this descriptor to lower case.
1.2153 +
1.2154 +Conversion is implemented as appropriate to the current locale.
1.2155 +*/
1.2156 + {
1.2157 +
1.2158 + TUint16 *pB=WPtr();
1.2159 + TInt len=Length();
1.2160 + while (len--)
1.2161 + {
1.2162 + TCharLC c(*pB);
1.2163 + *pB++=(TUint16)c;
1.2164 + }
1.2165 + }
1.2166 +
1.2167 +EXPORT_C void TDes16::UpperCase()
1.2168 +/**
1.2169 +Converts the content of this descriptor to upper case.
1.2170 +
1.2171 +Conversion is implemented as appropriate to the current locale.
1.2172 +*/
1.2173 + {
1.2174 +
1.2175 + TUint16 *pB=WPtr();
1.2176 + TInt len=Length();
1.2177 + while (len--)
1.2178 + {
1.2179 + TCharUC c(*pB);
1.2180 + *pB++=(TUint16)c;
1.2181 + }
1.2182 + }
1.2183 +
1.2184 +EXPORT_C void TDes16::Capitalize()
1.2185 +/**
1.2186 +Capitalises the content of this descriptor.
1.2187 +
1.2188 +Capitalisation is implemented as appropriate to the current locale.
1.2189 +*/
1.2190 + {
1.2191 +
1.2192 + TUint16 *pB=WPtr();
1.2193 + TInt len=Length();
1.2194 + if (len--)
1.2195 + {
1.2196 + *pB=(TUint16)User::TitleCase(*pB);
1.2197 + ++pB;
1.2198 + while (len--)
1.2199 + {
1.2200 + *pB=(TUint16)User::LowerCase(*pB);
1.2201 + ++pB;
1.2202 + }
1.2203 + }
1.2204 + }
1.2205 +
1.2206 +EXPORT_C void TDes16::CopyF(const TDesC16 &aDes)
1.2207 +/**
1.2208 +Copies and folds data from the specified descriptor into this descriptor replacing
1.2209 +any existing data.
1.2210 +
1.2211 +The length of this descriptor is set to reflect the new
1.2212 +data.
1.2213 +
1.2214 +Note that folding is locale-independent behaviour. It is also important to
1.2215 +note that there can be no guarantee that folding is in any way culturally
1.2216 +appropriate, and should not be used when dealing with strings in natural
1.2217 +language.
1.2218 +
1.2219 +@param aDes A 16-bit non-modifiable descriptor.
1.2220 +
1.2221 +@panic USER 11 if the length of aDes is greater than the maximum length of
1.2222 + this target descriptor.
1.2223 +*/
1.2224 + {
1.2225 +
1.2226 + TInt len=aDes.Length();
1.2227 + SetLength(len);
1.2228 + const TUint16 *pS=aDes.Ptr();
1.2229 + TUint16 *pT=WPtr();
1.2230 + while (len--)
1.2231 + {
1.2232 + TCharF c(*pS++);
1.2233 + *pT++=(TUint16)c;
1.2234 + }
1.2235 + }
1.2236 +
1.2237 +EXPORT_C void TDes16::CopyC(const TDesC16 &aDes)
1.2238 +/**
1.2239 +Copies and collates data from the specified descriptor
1.2240 +into this descriptor replacing any existing data.
1.2241 +
1.2242 +The length of this descriptor is set to reflect the new data.
1.2243 +
1.2244 +@param aDes A 16-bit non-modifiable descriptor.
1.2245 +
1.2246 +@panic USER 11 if the length of aDes is greater than the maximum length of
1.2247 + this target descriptor.
1.2248 +*/
1.2249 + {
1.2250 +
1.2251 + TInt len=aDes.Length();
1.2252 + SetLength(len);
1.2253 + const TUint16 *pS=aDes.Ptr();
1.2254 + TUint16 *pT=WPtr();
1.2255 + while (len--)
1.2256 + {
1.2257 + TChar c=User::Collate(*pS++);
1.2258 + *pT++=(TUint16)c;
1.2259 + }
1.2260 + }
1.2261 +
1.2262 +EXPORT_C void TDes16::CopyLC(const TDesC16 &aDes)
1.2263 +/**
1.2264 +Copies text from the specified descriptor and converts it to lower case before
1.2265 +putting it into this descriptor, replacing any existing data.
1.2266 +
1.2267 +The length of this descriptor is set to reflect the new data.
1.2268 +
1.2269 +Conversion to lower case is implemented as appropriate to the current locale.
1.2270 +
1.2271 +@param aDes A 16-bit non modifiable descriptor.
1.2272 +
1.2273 +@panic USER 11 if the length of aDes is greater than the maximum length of
1.2274 + this target descriptor.
1.2275 +*/
1.2276 + {
1.2277 +
1.2278 + TInt len=aDes.Length();
1.2279 + SetLength(len);
1.2280 + const TUint16 *pS=aDes.Ptr();
1.2281 + TUint16 *pT=WPtr();
1.2282 + while (len--)
1.2283 + {
1.2284 + TCharLC c(*pS++);
1.2285 + *pT++=(TUint16)c;
1.2286 + }
1.2287 + }
1.2288 +
1.2289 +EXPORT_C void TDes16::CopyUC(const TDesC16 &aDes)
1.2290 +/**
1.2291 +Copies text from the specified descriptor and converts it to upper case before
1.2292 +putting it into this descriptor, replacing any existing data.
1.2293 +
1.2294 +The length of this descriptor is set to reflect the new data.
1.2295 +
1.2296 +Conversion to upper case is implemented as appropriate to the current locale.
1.2297 +
1.2298 +@param aDes A 16-bit non modifiable descriptor.
1.2299 +
1.2300 +@panic USER 11 if the length of aDes is greater than the maximum length of
1.2301 + this target descriptor.
1.2302 +*/
1.2303 + {
1.2304 +
1.2305 + TInt len=aDes.Length();
1.2306 + SetLength(len);
1.2307 + const TUint16 *pS=aDes.Ptr();
1.2308 + TUint16 *pT=WPtr();
1.2309 + while (len--)
1.2310 + {
1.2311 + TCharUC c(*pS++);
1.2312 + *pT++=(TUint16)c;
1.2313 + }
1.2314 + }
1.2315 +
1.2316 +EXPORT_C void TDes16::CopyCP(const TDesC16 &aDes)
1.2317 +/**
1.2318 +Copies text from the specified descriptor and capitalises it before putting
1.2319 +it into this descriptor, replacing any existing data.
1.2320 +
1.2321 +The length of this descriptor is set to reflect the new data.
1.2322 +
1.2323 +Capitalisation is implemented as appropriate to the current locale.
1.2324 +
1.2325 +@param aDes A 16-bit non-modifiable descriptor.
1.2326 +
1.2327 +@panic USER 11 if the length of aDes is greater than the maximum length of
1.2328 + this target descriptor.
1.2329 +*/
1.2330 + {
1.2331 +
1.2332 + TInt len=aDes.Length();
1.2333 + SetLength(len);
1.2334 + const TUint16 *pS=aDes.Ptr();
1.2335 + TUint16 *pT=WPtr();
1.2336 + if (len--)
1.2337 + {
1.2338 + TChar c(*pS++);
1.2339 +#ifdef _UNICODE
1.2340 + c.TitleCase();
1.2341 +#else
1.2342 + c.UpperCase();
1.2343 +#endif
1.2344 + *pT++=(TUint16)c;
1.2345 + while (len--)
1.2346 + {
1.2347 + TCharLC c=(*pS++);
1.2348 + *pT++=(TUint16)c;
1.2349 + }
1.2350 + }
1.2351 + }
1.2352 +
1.2353 +EXPORT_C void TDes16::Repeat(const TUint16 *aBuf,TInt aLength)
1.2354 +/**
1.2355 +Copies data with repetition into this descriptor, from a memory location
1.2356 +specified by pointer, replacing any existing data.
1.2357 +
1.2358 +Copying proceeds until this descriptor is filled up to its current length.
1.2359 +If it cannot contain a whole number of copies of the source data, then the
1.2360 +last copy is truncated.
1.2361 +
1.2362 +@param aBuf A pointer to data to be repeatedly copied.
1.2363 +@param aLength The length of data to be copied.
1.2364 +
1.2365 +@panic USER 17 if aLength is negative.
1.2366 +*/
1.2367 + {
1.2368 +
1.2369 + __ASSERT_ALWAYS(aLength>=0,Panic(ETDes16LengthNegative));
1.2370 + __CHECK_ALIGNMENT(aBuf,ETDes16RepeatBufLength);
1.2371 + TUint16 *pB=WPtr();
1.2372 + TInt len=Length();
1.2373 + if (len && aLength)
1.2374 + {
1.2375 + while (len)
1.2376 + {
1.2377 + TInt i=Min(len,aLength);
1.2378 + pB=memCopy(pB,aBuf,i);
1.2379 + len-=i;
1.2380 + }
1.2381 + }
1.2382 + }
1.2383 +
1.2384 +EXPORT_C void TDes16::Repeat(const TDesC16 &aDes)
1.2385 +/**
1.2386 +Copies data with repetition into this descriptor, from another descriptor,
1.2387 +replacing any existing data.
1.2388 +
1.2389 +Copying proceeds until this descriptor is filled up to its current length.
1.2390 +If it cannot contain a whole number of copies of the source data, then the
1.2391 +last copy is truncated.
1.2392 +
1.2393 +@param aDes A 16-bit non modifiable descriptor whose data is to be repeatedly
1.2394 + copied.
1.2395 +*/
1.2396 + {
1.2397 +
1.2398 + Repeat(aDes.Ptr(),aDes.Length());
1.2399 + }
1.2400 +
1.2401 +EXPORT_C void TDes16::Trim()
1.2402 +/**
1.2403 +Deletes leading and trailing whitespace characters from the descriptor's data.
1.2404 +
1.2405 +The length of the descriptor is reduced to reflect the loss of the whitespace characters.
1.2406 +
1.2407 +@see TDes16::TrimLeft()
1.2408 +@see TDes16::TrimRight()
1.2409 +*/
1.2410 + {
1.2411 +
1.2412 + TrimLeft();
1.2413 + TrimRight();
1.2414 + }
1.2415 +
1.2416 +EXPORT_C void TDes16::TrimAll()
1.2417 +/**
1.2418 +Deletes leading and trailing whitespace characters from the descriptor's data
1.2419 +and replaces each contiguous set of whitespace characters within the data by one
1.2420 +whitespace character.
1.2421 +
1.2422 +The length of the descriptor is reduced to reflect the loss of the whitespace
1.2423 +characters.
1.2424 +
1.2425 +@see TDes16::Trim()
1.2426 +*/
1.2427 + {
1.2428 +
1.2429 + TrimLeft();
1.2430 + TrimRight();
1.2431 + TUint16 *pBuf=(TUint16 *)Ptr();
1.2432 + TUint16 *pSrc=pBuf;
1.2433 + TUint16 *pDst=pBuf;
1.2434 + TInt len=Length();
1.2435 + TInt spaces=0;
1.2436 + while (len--)
1.2437 + {
1.2438 + TChar c=*pSrc;
1.2439 + if (c.IsSpace())
1.2440 + {
1.2441 + if (spaces++==0)
1.2442 + {
1.2443 + if (pDst!=pSrc)
1.2444 + *pDst=*pSrc;
1.2445 + pDst++;
1.2446 + }
1.2447 + }
1.2448 + else
1.2449 + {
1.2450 + spaces=0;
1.2451 + if (pDst!=pSrc)
1.2452 + *pDst=*pSrc;
1.2453 + pDst++;
1.2454 + }
1.2455 + pSrc++;
1.2456 + }
1.2457 + Delete(pDst-pBuf, pSrc-pDst);
1.2458 + }
1.2459 +
1.2460 +EXPORT_C void TDes16::TrimLeft()
1.2461 +/**
1.2462 +Deletes leading whitespace characters from the descriptor's data.
1.2463 +
1.2464 +All whitespace characters up to, but not including the first
1.2465 +non-whitespace character, are deleted.
1.2466 +
1.2467 +The length of the descriptor is reduced to reflect the loss
1.2468 +of the whitespace characters.
1.2469 +*/
1.2470 + {
1.2471 +
1.2472 + const TUint16 *pBuf=Ptr();
1.2473 + const TUint16 *pB=pBuf;
1.2474 + TInt len=Length();
1.2475 + while (len--)
1.2476 + {
1.2477 + TChar c=(*pB);
1.2478 + if (!c.IsSpace())
1.2479 + break;
1.2480 + pB++;
1.2481 + }
1.2482 + Delete(0,pB-pBuf);
1.2483 + }
1.2484 +
1.2485 +EXPORT_C void TDes16::TrimRight()
1.2486 +/**
1.2487 +Deletes trailing whitespace characters from the descriptor's data.
1.2488 +
1.2489 +The process starts on the right hand side of the descriptor's data
1.2490 +and proceeds to the left.
1.2491 +
1.2492 +All whitespace characters up to, but not including the first non-whitespace character,
1.2493 +are deleted.
1.2494 +
1.2495 +The length of the descriptor is reduced to reflect the loss of the whitespace
1.2496 +characters.
1.2497 +*/
1.2498 + {
1.2499 +
1.2500 + TInt len=Length();
1.2501 + if (len==0)
1.2502 + return;
1.2503 + const TUint16 *pB=Ptr()+len-1;
1.2504 + TInt s=len;
1.2505 + while (s)
1.2506 + {
1.2507 + TChar c=(*pB--);
1.2508 + if (!c.IsSpace())
1.2509 + break;
1.2510 + s--;
1.2511 + }
1.2512 + Delete(s,len-s);
1.2513 + }
1.2514 +
1.2515 +EXPORT_C void TDes16::Insert(TInt aPos,const TDesC16 &aDes)
1.2516 +/**
1.2517 +Inserts data into this descriptor.
1.2518 +
1.2519 +The length of this descriptor is changed to reflect the extra data.
1.2520 +
1.2521 +@param aPos The position within the data where insertion is to start. This
1.2522 + is an offset value; a zero value refers to the leftmost data
1.2523 + position.
1.2524 +
1.2525 +@param aDes A 16-bit non modifiable descriptor whose data is to be inserted.
1.2526 +
1.2527 +@panic USER 10 if aPos is negative or is greater than the length of this
1.2528 + descriptor.
1.2529 +@panic USER 11 if the resulting length of this descriptor is greater than its
1.2530 + maximum length.
1.2531 +*/
1.2532 + {
1.2533 +
1.2534 + TInt len=Length();
1.2535 + __ASSERT_ALWAYS(aPos>=0 && aPos<=len,Panic(ETDes16PosOutOfRange));
1.2536 + TInt s=aDes.Length();
1.2537 + __ASSERT_ALWAYS((len+s)<=MaxLength(),Panic(ETDes16Overflow));
1.2538 + TUint16 *pB=WPtr();
1.2539 + memCopy(pB+aPos+s,pB+aPos,len-aPos);
1.2540 + memCopy(pB+aPos,aDes.Ptr(),aDes.Length());
1.2541 + SetLength(len+s);
1.2542 + }
1.2543 +
1.2544 +EXPORT_C void TDes16::Delete(TInt aPos,TInt aLength)
1.2545 +/**
1.2546 +Deletes data from this descriptor.
1.2547 +
1.2548 +The length of this descriptor is changed to reflect the loss of data.
1.2549 +
1.2550 +@param aPos The position within the data where deletion is to start. This
1.2551 + is an offset value; a zero value refers to the leftmost data
1.2552 + position.
1.2553 +
1.2554 +@param aLength The length of data to be deleted. If necessary, the function
1.2555 + adjusts this value to ensure that no data beyond the end of
1.2556 + the descriptor data area is deleted.
1.2557 +
1.2558 +@panic USER 10 if aPos is negative or is greater than the length of this
1.2559 + descriptor.
1.2560 +*/
1.2561 + {
1.2562 +
1.2563 + TInt len=Length();
1.2564 + __ASSERT_ALWAYS(aPos>=0 && aPos<=len,Panic(ETDes16PosOutOfRange));
1.2565 + TInt d=Min(len-aPos,aLength);
1.2566 + TUint16 *pB=WPtr();
1.2567 + memCopy(pB+aPos,pB+aPos+d,len-aPos-d);
1.2568 + SetLength(len-d);
1.2569 + }
1.2570 +
1.2571 +EXPORT_C void TDes16::Replace(TInt aPos,TInt aLength,const TDesC16 &aDes)
1.2572 +/**
1.2573 +Replaces data in this descriptor.
1.2574 +
1.2575 +The specified length can be different to the length of the replacement data.
1.2576 +The length of this descriptor changes to reflect the change of data.
1.2577 +
1.2578 +@param aPos The position within the data where replacement is to start.
1.2579 + This is an offset value; a zero value refers to the leftmost
1.2580 + data position.
1.2581 +
1.2582 +@param aLength The length of data to be replaced.
1.2583 +
1.2584 +@param aDes The source 16-bit non modifiable descriptor whose data is to
1.2585 + replace the target descriptor's data at aPos.
1.2586 +
1.2587 +@panic USER 8 if aLength is negative or the sum of aLength and aPos is
1.2588 + greater than the length of this descriptor.
1.2589 +
1.2590 +@panic USER 10 if aPos is negative or is greater than the length of this
1.2591 + descriptor.
1.2592 +
1.2593 +@panic USER 11 if the resulting length of this descriptor is greater than its
1.2594 + maximum length.
1.2595 +
1.2596 +@panic USER 16 if the length of the source descriptor aDes is negative or is
1.2597 + greater than the maximum length of this target descriptor,
1.2598 +*/
1.2599 + {
1.2600 +
1.2601 + TInt len=Length();
1.2602 + __ASSERT_ALWAYS(aPos>=0 && aPos<=len,Panic(ETDes16PosOutOfRange));
1.2603 + __ASSERT_ALWAYS(aLength>=0 && aPos+aLength<=len,Panic(ETDes16LengthOutOfRange));
1.2604 + TInt s=aDes.Length();
1.2605 + TInt maxlen=MaxLength();
1.2606 + __ASSERT_ALWAYS(s>=0 && s<=maxlen,Panic(ETDes16RemoteLengthOutOfRange));
1.2607 + __ASSERT_ALWAYS((len+s-aLength)<=maxlen,Panic(ETDes16Overflow));
1.2608 + TUint16 *pB=WPtr();
1.2609 + memCopy(pB+aPos+s,pB+aPos+aLength,len-aPos-aLength);
1.2610 + memCopy(pB+aPos,aDes.Ptr(),s);
1.2611 + SetLength(len+s-aLength);
1.2612 + }
1.2613 +
1.2614 +EXPORT_C void TDes16::Justify(const TDesC16 &aDes,TInt aWidth,TAlign anAlignment,TChar aFill)
1.2615 +/**
1.2616 +Copies data into this descriptor and justifies it, replacing any existing data.
1.2617 +
1.2618 +The length of this descriptor is set to reflect the new data.
1.2619 +
1.2620 +The target area is considered to be an area of specified width positioned at
1.2621 +the beginning of this descriptor's data area. Source data is copied into, and
1.2622 +aligned within this target area according to the specified alignment
1.2623 +instruction.
1.2624 +
1.2625 +If the length of the target area is larger than the length of the source, then
1.2626 +spare space within the target area is padded with the fill character.
1.2627 +
1.2628 +@param aDes A 16-bit non-modifiable descriptor containing the source data.
1.2629 + The length of the data to be copied is the smaller of:
1.2630 + the length of the source descriptor, and
1.2631 + the width of the target area (only if this is not the
1.2632 + explicit negative value KDefaultJustifyWidth).
1.2633 +
1.2634 +@param aWidth The width of the target area. If this has the specific
1.2635 + negative value KDefaultJustifyWidth, then the width is
1.2636 + re-set to the length of the data source.
1.2637 +
1.2638 +@param anAlignment The alignment of the data within the target area
1.2639 +
1.2640 +@param aFill The fill character used to pad the target area.
1.2641 +
1.2642 +@panic USER 11 if the resulting length of this descriptor is greater than
1.2643 + its maximum length or aWidth has a negative value other
1.2644 + than KDefaultJustifyWidth.
1.2645 +*/
1.2646 + {
1.2647 +
1.2648 + Zero();
1.2649 + AppendJustify(aDes.Ptr(),aDes.Length(),aWidth,anAlignment,aFill);
1.2650 + }
1.2651 +
1.2652 +EXPORT_C void TDes16::AppendJustify(const TDesC16 &aDes,TInt aWidth,TAlign anAlignment,TChar aFill)
1.2653 +/**
1.2654 +Appends data onto the end of this descriptor's data and justifies it.
1.2655 +
1.2656 +The source of the appended data is an existing descriptor.
1.2657 +
1.2658 +The target area is considered to be an area of specified width, immediately
1.2659 +following this descriptor's existing data. Source data is copied into, and
1.2660 +aligned within this target area according to the specified alignment instruction.
1.2661 +
1.2662 +If the length of the target area is larger than the length of the source,
1.2663 +then spare space within the target area is padded with the fill character.
1.2664 +
1.2665 +@param aDes A 16-bit non-modifiable descriptor containing the source
1.2666 + data. The length of the data to be copied is the smaller of:
1.2667 + the length of the source descriptor, and
1.2668 + the width of the target area (only if this is not the
1.2669 + explicit negative value KDefaultJustifyWidth).
1.2670 +
1.2671 +@param aWidth The width of the target area. If this has the specific
1.2672 + negative value KDefaultJustifyWidth, then the width is
1.2673 + re-set to the length of the data source.
1.2674 +
1.2675 +@param anAlignment The alignment of the data within the target area.
1.2676 +
1.2677 +@param aFill The fill character used to pad the target area.
1.2678 +
1.2679 +@panic USER 11 if the resulting length of this descriptor is greater than
1.2680 + its maximum length or aWidth has a negative value other
1.2681 + than KDefaultJustifyWidth.
1.2682 +*/
1.2683 + {
1.2684 +
1.2685 + AppendJustify(aDes.Ptr(),aDes.Length(),aWidth,anAlignment,aFill);
1.2686 + }
1.2687 +
1.2688 +EXPORT_C void TDes16::AppendJustify(const TDesC16 &aDes,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill)
1.2689 +/**
1.2690 +Appends data onto the end of this descriptor's data and justifies it.
1.2691 +
1.2692 +The source of the appended data is an existing descriptor.
1.2693 +
1.2694 +The target area is considered to be an area of specified width, immediately
1.2695 +following this descriptor's existing data. Source data is copied into, and
1.2696 +aligned within this target area according to the specified alignment instruction.
1.2697 +
1.2698 +If the length of the target area is larger than the length of the source,
1.2699 +then spare space within the target area is padded with the fill character.
1.2700 +
1.2701 +@param aDes An 8-bit non-modifiable descriptor containing the source data.
1.2702 +
1.2703 +@param aLength The length of data to be copied from the source descriptor.
1.2704 + If this is greater than the width of the target area, then
1.2705 + the length of data copied is limited to the width.
1.2706 + The length of data to be copied must not be greater than
1.2707 + the length of the source descriptor. Note that this
1.2708 + condition is not automatically tested.
1.2709 +
1.2710 +@param aWidth The width of the target area. If this has the specific negative
1.2711 + value KDefaultJustifyWidth, then the width is
1.2712 + re-set to the length of the data source.
1.2713 +
1.2714 +@param anAlignment The alignment of the data within the target area.
1.2715 +
1.2716 +@param aFill The fill character used to pad the target area.
1.2717 +
1.2718 +@panic USER 11 if the resulting length of this descriptor is greater than
1.2719 + its maximum length or aWidth has a negative value other
1.2720 + than KDefaultJustifyWidth.
1.2721 +*/
1.2722 + {
1.2723 +
1.2724 + AppendJustify(aDes.Ptr(),aLength,aWidth,anAlignment,aFill);
1.2725 + }
1.2726 +
1.2727 +EXPORT_C void TDes16::AppendJustify(const TUint16 *aString,TInt aWidth,TAlign anAlignment,TChar aFill)
1.2728 +/**
1.2729 +Appends a zero terminated string onto the end of this descriptor's data and
1.2730 +justifies it.
1.2731 +
1.2732 +The zero terminator is not copied.
1.2733 +
1.2734 +The target area is considered to be an area of specified width, immediately
1.2735 +following this descriptor's existing data. Source data is copied into, and
1.2736 +aligned within, this target area according to the specified alignment instruction.
1.2737 +
1.2738 +If the length of the target area is larger than the length of the source,
1.2739 +then spare space within the target area is padded with the fill character.
1.2740 +
1.2741 +@param aString A pointer to a zero terminated string The length of the data
1.2742 + to be copied is the smaller of: the length of the string (excluding the zero
1.2743 + terminator), the width of the target area (only if this is not the explicit
1.2744 + negative value KDefaultJustifyWidth).
1.2745 +
1.2746 +@param aWidth The width of the target area. If this has the specific negative
1.2747 + value KDefaultJustifyWidth, then the width is re-set to the length of the
1.2748 + zero terminated string (excluding the zero terminator).
1.2749 +
1.2750 +@param anAlignment The alignment of the data within the target area.
1.2751 +
1.2752 +@param aFill The fill character used to pad the target area.
1.2753 +
1.2754 +@panic USER 11 if the resulting length of this descriptor is greater than
1.2755 + its maximum length or aWidth has a negative value other
1.2756 + than KDefaultJustifyWidth.
1.2757 +*/
1.2758 + {
1.2759 +
1.2760 + __CHECK_ALIGNMENT(aString,ETDes16AppendJustify1);
1.2761 + AppendJustify(aString,STRING_LENGTH_16(aString),aWidth,anAlignment,aFill);
1.2762 + }
1.2763 +
1.2764 +EXPORT_C void TDes16::AppendJustify(const TUint16 *aString,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill)
1.2765 +/**
1.2766 +Appends data onto the end of this descriptor's data and justifies it.
1.2767 +
1.2768 +The source of the appended data is a memory location.
1.2769 +
1.2770 +The target area is considered to be an area of specified width, immediately
1.2771 +following this descriptor's existing data. Source data is copied into, and
1.2772 +aligned within, this target area according to the specified alignment instruction.
1.2773 +
1.2774 +If the length of the target area is larger than the length of the source,
1.2775 +then spare space within the target area is padded with the fill character.
1.2776 +
1.2777 +@param aString A pointer to a source memory location.
1.2778 +
1.2779 +@param aLength The length of data to be copied. If this is greater than the
1.2780 + width of the target area, then the length of data copied is
1.2781 + limited to the width.
1.2782 +
1.2783 +@param aWidth The width of the target area. If this has the specific negative
1.2784 + value KDefaultJustifyWidth, then the width is
1.2785 + re-set to the length of the data source.
1.2786 +
1.2787 +@param anAlignment The alignment of the data within the target area.
1.2788 +
1.2789 +@param aFill The fill character used to pad the target area.
1.2790 +
1.2791 +@panic USER 11 if the resulting length of this descriptor is greater than
1.2792 + its maximum length or aWidth has a negative value other
1.2793 + than KDefaultJustifyWidth.
1.2794 +
1.2795 +@panic USER 17 if aLength is negative.
1.2796 +*/
1.2797 + {
1.2798 +
1.2799 + __ASSERT_ALWAYS(aLength>=0,Panic(ETDes16LengthNegative));
1.2800 + __CHECK_ALIGNMENT(aString,ETDes16AppendJustify2);
1.2801 + if (aWidth==KDefaultJustifyWidth)
1.2802 + aWidth=aLength;
1.2803 + if (aLength>aWidth)
1.2804 + aLength=aWidth;
1.2805 + TInt offset=Length();
1.2806 + AppendFill(aFill,aWidth);
1.2807 + TInt r=aWidth-aLength;
1.2808 + if (anAlignment==ECenter)
1.2809 + r>>=1;
1.2810 + else if (anAlignment==ELeft)
1.2811 + r=0;
1.2812 + memCopy(WPtr()+offset+r,aString,aLength);
1.2813 + }
1.2814 +
1.2815 +EXPORT_C void TDes16::NumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth)
1.2816 +/**
1.2817 +Converts the specified unsigned integer into a fixed width character
1.2818 +representation based on the specified number system and copies the conversion
1.2819 +into this descriptor, replacing any existing data.
1.2820 +
1.2821 +The length of this descriptor is set to reflect the new data.
1.2822 +
1.2823 +The function generates the exact number of specified characters, either padding
1.2824 +to the left with character zeroes or discarding low order characters as necessary.
1.2825 +
1.2826 +When a hexadecimal conversion is specified, hexadecimal characters are in
1.2827 +lower case.
1.2828 +
1.2829 +This function is equivalent to using Format() with parameters which specify:
1.2830 +
1.2831 +1. a fixed length target field
1.2832 +
1.2833 +2. padding with zero characters, for example "%08x".
1.2834 +
1.2835 +When this is the case, always use NumFixedWidth() in preference
1.2836 +to Format() as it is more efficient.
1.2837 +
1.2838 +@param aVal The unsigned integer value.
1.2839 +@param aRadix The number system representation for the unsigned integer.
1.2840 +@param aWidth The number of characters: to be used to contain the conversion,
1.2841 + to be copied into this descriptor.
1.2842 +*/
1.2843 + {
1.2844 +
1.2845 + Zero();
1.2846 + AppendNumFixedWidth(aVal,aRadix,aWidth);
1.2847 + }
1.2848 +
1.2849 +EXPORT_C void TDes16::NumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth)
1.2850 +/**
1.2851 +Converts the specified unsigned integer into a fixed width character
1.2852 +representation based on the specified number system and copies the conversion
1.2853 +into this descriptor, replacing any existing data.
1.2854 +
1.2855 +The length of this descriptor is set to reflect the new data.
1.2856 +
1.2857 +The function generates the exact number of specified characters, either padding
1.2858 +to the left with character zeroes or discarding low order characters as
1.2859 +necessary.
1.2860 +
1.2861 +When a hexadecimal conversion is specified, hexadecimal characters are in
1.2862 +upper case.
1.2863 +
1.2864 +This function is equivalent to using Format() with parameters which specify:
1.2865 +
1.2866 +1. a fixed length target field
1.2867 +
1.2868 +2. padding with zero characters, for example "%08x".
1.2869 +
1.2870 +When this is the case, always use NumFixedWidthUC() in
1.2871 +preference to Format() as it is more efficient.
1.2872 +
1.2873 +@param aVal The unsigned integer value.
1.2874 +@param aRadix The number system representation for the unsigned integer.
1.2875 +@param aWidth The number of characters: to be used to contain the conversion,
1.2876 + to be copied into this descriptor.
1.2877 +
1.2878 +@see TDes16::Format()
1.2879 +*/
1.2880 + {
1.2881 +
1.2882 + Zero();
1.2883 + AppendNumFixedWidthUC(aVal,aRadix,aWidth);
1.2884 + }
1.2885 +
1.2886 +EXPORT_C void TDes16::Num(TInt64 aVal)
1.2887 +/**
1.2888 +Converts the 64-bit signed integer into a decimal character representation
1.2889 +and copies the conversion into this descriptor, replacing any existing data.
1.2890 +
1.2891 +The length of this descriptor is set to reflect the new data.
1.2892 +
1.2893 +If the integer is negative, the character representation is prefixed by a
1.2894 +minus sign.
1.2895 +
1.2896 +@param aVal The 64-bit signed integer value.
1.2897 +*/
1.2898 + {
1.2899 + Zero();
1.2900 + AppendNum(aVal);
1.2901 + }
1.2902 +
1.2903 +EXPORT_C void TDes16::Num(TUint64 aVal, TRadix aRadix)
1.2904 +/**
1.2905 +Converts the specified 64 bit unsigned integer into a character representation
1.2906 +based on the specified number system and copies the conversion into this
1.2907 +descriptor, replacing any existing data.
1.2908 +
1.2909 +The length of this descriptor is set to reflect the new data.
1.2910 +
1.2911 +When a hexadecimal conversion is specified, hexadecimal characters are in
1.2912 +lower case.
1.2913 +
1.2914 +@param aVal The 64 bit integer value. This is treated as an unsigned
1.2915 + value for all builds.
1.2916 +@param aRadix The number system representation for the 64 bit integer.
1.2917 +*/
1.2918 + {
1.2919 +
1.2920 + Zero();
1.2921 + AppendNum(aVal,aRadix);
1.2922 + }
1.2923 +
1.2924 +EXPORT_C void TDes16::NumUC(TUint64 aVal, TRadix aRadix)
1.2925 +/**
1.2926 +Converts the specified 64 bit unsigned integer into a character representation
1.2927 +based on the specified number system and copies the conversion into this
1.2928 +descriptor, replacing any existing data.
1.2929 +
1.2930 +The length of this descriptor is set to reflect the new data.
1.2931 +
1.2932 +When a hexadecimal conversion is specified, hexadecimal characters are in
1.2933 +upper case.
1.2934 +
1.2935 +@param aVal The 64 bit integer value. This is always treated as an unsigned
1.2936 + value for all builds.
1.2937 +@param aRadix The number system representation for the 64 bit integer. If no
1.2938 + explicit value is specified, then EDecimal is the default.
1.2939 +*/
1.2940 + {
1.2941 +
1.2942 + Zero();
1.2943 + AppendNumUC(aVal,aRadix);
1.2944 + }
1.2945 +
1.2946 +void TDes16::DoPadAppendNum(TInt l, TInt aW, const TUint8* p)
1.2947 + {
1.2948 + __ASSERT_DEBUG( ((l|(TInt)p)&1)==0, Panic(EDes16PadAppendBadAlign));
1.2949 + l>>=1;
1.2950 + if (aW<=0)
1.2951 + {
1.2952 + Append((const TUint16*)p, l);
1.2953 + return;
1.2954 + }
1.2955 + TInt l0 = Length();
1.2956 + SetLength(l0 + aW);
1.2957 + TUint16* d = WPtr() + l0;
1.2958 + for (; aW>l; --aW) *d++ = (TUint16)'0';
1.2959 + memcpy(d, p, aW*2);
1.2960 + }
1.2961 +
1.2962 +EXPORT_C void TDes16::AppendNumFixedWidth(TUint aVal,TRadix aRadix,TInt aWidth)
1.2963 +/**
1.2964 +Converts the specified unsigned integer into a fixed width character
1.2965 +representation based on the specified number system and appends the conversion
1.2966 +onto the end of this descriptor's data.
1.2967 +
1.2968 +The length of this descriptor is incremented to reflect the new content.
1.2969 +
1.2970 +The function generates the exact number of specified characters, either padding
1.2971 +to the left with character zeroes or discarding low order characters as
1.2972 +necessary.
1.2973 +
1.2974 +When a hexadecimal conversion is specified, hexadecimal characters are in
1.2975 +lower case.
1.2976 +
1.2977 +@param aVal The unsigned integer value.
1.2978 +@param aRadix The number system representation for the unsigned integer.
1.2979 +@param aWidth The number of characters to be used to contain the conversion,
1.2980 + and to be appended to this descriptor.
1.2981 +*/
1.2982 + {
1.2983 +
1.2984 + TBuf16<32> buf;
1.2985 + buf.Num(aVal,aRadix);
1.2986 + if (buf.Length()>=aWidth)
1.2987 + Append(buf.Left(aWidth));
1.2988 + else
1.2989 + {
1.2990 + TInt i=aWidth-buf.Length();
1.2991 + while(i--)
1.2992 + Append(TChar('0'));
1.2993 + Append(buf);
1.2994 + }
1.2995 + }
1.2996 +
1.2997 +#ifndef __DES16_MACHINE_CODED__
1.2998 +EXPORT_C TPtr16 TDes16::LeftTPtr(TInt aLength) const
1.2999 +/**
1.3000 +Extracts the leftmost part of the data.
1.3001 +
1.3002 +The function does not cut or remove any data but constructs a modifiable pointer
1.3003 +descriptor to represent the leftmost part of the data.
1.3004 +
1.3005 +@param aLength The length of the data to be extracted. If this value is
1.3006 + greater than the length of the descriptor, the function
1.3007 + extracts the whole of the descriptor.
1.3008 +
1.3009 +@return The 16-bit modifiable pointer descriptor representing the leftmost part
1.3010 + of the data.
1.3011 +
1.3012 +@panic USER 10 if aLength is negative.
1.3013 +*/
1.3014 + {
1.3015 +
1.3016 + __ASSERT_ALWAYS(aLength>=0,Panic(ETDes16PosOutOfRange));
1.3017 + TInt len = Min(aLength,Length());
1.3018 + return(TPtr16((TUint16*)Ptr(),len,len));
1.3019 + }
1.3020 +
1.3021 +EXPORT_C TPtr16 TDes16::RightTPtr(TInt aLength) const
1.3022 +/**
1.3023 +Extracts the rightmost part of the data.
1.3024 +
1.3025 +The function does not cut or remove any data but constructs a modifiable pointer
1.3026 +descriptor to represent the rightmost part of the data.
1.3027 +
1.3028 +@param aLength The length of data to be extracted. If this value
1.3029 + is greater than the length of the descriptor, the function
1.3030 + extracts the whole of the descriptor.
1.3031 +
1.3032 +@return The 16-bit modifiable pointer descriptor representing the rightmost part
1.3033 + of the data.
1.3034 +
1.3035 +@panic USER 10 if aLength is negative.
1.3036 +*/
1.3037 + {
1.3038 +
1.3039 + __ASSERT_ALWAYS(aLength>=0,Panic(ETDes16PosOutOfRange));
1.3040 + TInt len=Length();
1.3041 + if (aLength>len)
1.3042 + aLength=len;
1.3043 + return(TPtr16((TUint16*)Ptr()+len-aLength,aLength,aLength));
1.3044 + }
1.3045 +
1.3046 +EXPORT_C TPtr16 TDes16::MidTPtr(TInt aPos) const
1.3047 +/**
1.3048 +Extracts a portion of the data.
1.3049 +
1.3050 +The function does not cut or remove any data but constructs a modifiable pointer
1.3051 +descriptor to represent the defined portion.
1.3052 +
1.3053 +The portion is identified by its starting position and by the length of the
1.3054 +remainder of the data starting from the specified position.
1.3055 +
1.3056 +@param aPos The starting position of the data to be extracted. This is an
1.3057 + offset value; a zero value refers to the leftmost data position.
1.3058 +
1.3059 +@return The 16-bit modifiable pointer descriptor representing the specified
1.3060 + portion of the data.
1.3061 +
1.3062 +@panic USER 10 if aPos is negative or aPos is greater than the
1.3063 + length of the descriptor.
1.3064 +*/
1.3065 + {
1.3066 +
1.3067 + TInt len=Length();
1.3068 + __ASSERT_ALWAYS(aPos>=0 && aPos<=len,Panic(ETDes16PosOutOfRange));
1.3069 + return(TPtr16((TUint16*)Ptr()+aPos,len-aPos,len-aPos));
1.3070 + }
1.3071 +
1.3072 +EXPORT_C TPtr16 TDes16::MidTPtr(TInt aPos,TInt aLength) const
1.3073 +/**
1.3074 +Extracts a portion of the data.
1.3075 +
1.3076 +The function does not cut or remove any data but constructs a modifiable pointer
1.3077 +descriptor to represent the defined portion.
1.3078 +
1.3079 +The portion is identified by its starting position and by its length.
1.3080 +
1.3081 +@param aPos The starting position of the data to be extracted. This is an
1.3082 + offset value; a zero value refers to the leftmost data position.
1.3083 +@param aLength The length of data to be extracted.
1.3084 +
1.3085 +@return The 16-bit modifiable pointer descriptor representing the specified
1.3086 + portion of the data.
1.3087 +
1.3088 +@panic USER 10 if aPos is negative or aPos plus aLength is greater than the
1.3089 + length of the descriptor.
1.3090 +*/
1.3091 + {
1.3092 +
1.3093 + __ASSERT_ALWAYS(aPos>=0 && (aPos+aLength)<=Length(),Panic(ETDes16PosOutOfRange));
1.3094 + return(TPtr16((TUint16*)Ptr()+aPos,aLength,aLength));
1.3095 + }
1.3096 +#endif
1.3097 +
1.3098 +EXPORT_C void TDes16::AppendNumFixedWidthUC(TUint aVal,TRadix aRadix,TInt aWidth)
1.3099 +/**
1.3100 +Converts the specified unsigned integer into a fixed width character
1.3101 +representation based on the specified number system and appends the conversion
1.3102 +onto the end of this descriptor's data.
1.3103 +
1.3104 +The length of this descriptor is incremented to reflect the new content.
1.3105 +
1.3106 +The function generates the exact number of specified characters, either
1.3107 +padding to the left with character zeroes or discarding low order characters
1.3108 +as necessary.
1.3109 +
1.3110 +When a hexadecimal conversion is specified, hexadecimal characters are in
1.3111 +upper case.
1.3112 +
1.3113 +@param aVal The unsigned integer value.
1.3114 +@param aRadix The number system representation for the unsigned integer.
1.3115 +@param aWidth The number of characters: to be used to contain the conversion,
1.3116 + to be appended to this descriptor.
1.3117 +*/
1.3118 + {
1.3119 +
1.3120 + TBuf16<32> buf;
1.3121 + buf.NumUC(aVal,aRadix);
1.3122 + if (buf.Length()>=aWidth)
1.3123 + Append(buf.Left(aWidth));
1.3124 + else
1.3125 + {
1.3126 + TInt i=aWidth-buf.Length();
1.3127 + while(i--)
1.3128 + Append(TChar('0'));
1.3129 + Append(buf);
1.3130 + }
1.3131 + }
1.3132 +
1.3133 +EXPORT_C void TDes16::AppendNum(TInt64 aVal)
1.3134 +/**
1.3135 +Converts the 64-bit signed integer into a decimal character representation
1.3136 +and appends the conversion onto the end of this descriptor's data.
1.3137 +
1.3138 +The length of this descriptor is incremented to reflect the new content.
1.3139 +
1.3140 +If the integer is negative, the character representation is prefixed by a
1.3141 +minus sign.
1.3142 +
1.3143 +@param aVal The 64-bit signed integer value.
1.3144 +*/
1.3145 + {
1.3146 +
1.3147 + if (aVal<0)
1.3148 + {
1.3149 + Append('-');
1.3150 + aVal=-aVal;
1.3151 + }
1.3152 + AppendNum(static_cast<TUint64>(aVal), EDecimal);
1.3153 + }
1.3154 +
1.3155 +void TDes16::DoAppendNum(TUint64 aVal, TRadix aRadix, TUint aA, TInt aW)
1.3156 +//
1.3157 +// Convert a TUint64 into the descriptor.
1.3158 +//
1.3159 + {
1.3160 +
1.3161 + TUint16 buf[APPEND_BUF_SIZE_64];
1.3162 + TUint8* p = (TUint8*)(buf + APPEND_BUF_SIZE_64);
1.3163 + TInt l = __DoConvertNum(aVal, aRadix, aA|256, p);
1.3164 + // coverity[overrun-local]
1.3165 + DoPadAppendNum(l, aW, p);
1.3166 + }
1.3167 +
1.3168 +EXPORT_C void TDes16::AppendNum(TUint64 aVal, TRadix aRadix)
1.3169 +/**
1.3170 +Converts the specified 64 bit integer into a character representation
1.3171 +based on the specified number system and appends the conversion onto the end
1.3172 +of this descriptor's data.
1.3173 +
1.3174 +The length of this descriptor is incremented to reflect the new content.
1.3175 +
1.3176 +When a hexadecimal conversion is specified, hexadecimal characters are in
1.3177 +lower case.
1.3178 +
1.3179 +@param aVal The 64 bit integer value. This is always treated as an unsigned
1.3180 + value.
1.3181 +@param aRadix The number system representation for the 64 bit integer.
1.3182 +*/
1.3183 + {
1.3184 + DoAppendNum(aVal, aRadix, 'a', 0);
1.3185 + }
1.3186 +
1.3187 +EXPORT_C void TDes16::AppendNumUC(TUint64 aVal,TRadix aRadix)
1.3188 +/**
1.3189 +Converts the specified 64 bit integer into a character representation
1.3190 +based on the specified number system and appends the conversion onto the end
1.3191 +of this descriptor's data.
1.3192 +
1.3193 +The length of this descriptor is incremented to reflect the new content.
1.3194 +
1.3195 +When a hexadecimal conversion is specified, hexadecimal characters are in
1.3196 +upper case.
1.3197 +
1.3198 +@param aVal The 64 bit integer value. This is always treated as an unsigned
1.3199 + value.
1.3200 +@param aRadix The number system representation for the 64 bit integer. If no
1.3201 + explicit value is specified, then EDecimal is the default.
1.3202 +*/
1.3203 +
1.3204 + {
1.3205 + DoAppendNum(aVal, aRadix, 'A', 0);
1.3206 + }
1.3207 +
1.3208 +EXPORT_C void TDes16::Format(TRefByValue<const TDesC16> aFmt,...)
1.3209 +/**
1.3210 +Formats and copies text into this descriptor, replacing any existing data.
1.3211 +
1.3212 +The length of this descriptor is set to reflect the new data.
1.3213 +
1.3214 +The function takes a format string and a variable number of arguments.
1.3215 +The format string contains literal text embedded with directives for converting
1.3216 +the trailing list of arguments into text.
1.3217 +
1.3218 +The embedded directives are character sequences prefixed with the '%' character.
1.3219 +The literal text is simply copied into this descriptor unaltered while
1.3220 +the '%' directives are used to convert successive arguments from the
1.3221 +trailing list.
1.3222 +
1.3223 +The resulting stream of literal text and converted arguments is copied into
1.3224 +this descriptor.
1.3225 +
1.3226 +The syntax of the embedded directives follows one of four general patterns.
1.3227 +
1.3228 +Note that formatting of single numerical values can be achieved more
1.3229 +conveniently using the Num() and NumUC() member functions of this class.
1.3230 +
1.3231 +The full description of the syntax of a format string cannot be included here.
1.3232 +For full details, navigate to the Symbian OS guide, and follow the hierarchy of links:
1.3233 +
1.3234 +@code
1.3235 +Symbian OS Guide
1.3236 + Base
1.3237 + Using User Library (E32)
1.3238 + Buffers and Strings
1.3239 + Using Descriptors
1.3240 + How to Use Descriptors
1.3241 + Format string syntax
1.3242 +@endcode
1.3243 +
1.3244 +@param aFmt The descriptor containing the format string.
1.3245 + The TRefByValue class provides a constructor which takes a
1.3246 + TDesC8 type.
1.3247 +
1.3248 +@param ... A variable number of arguments to be converted to text as
1.3249 + dictated by the format string.
1.3250 +
1.3251 +@panic USER 11 if the resulting length of text in this descriptor exceeds
1.3252 + the descriptor's maximum length.
1.3253 +@panic USER 12 if the format string has incorrect syntax.
1.3254 +
1.3255 +@see TDes16::Num()
1.3256 +@see TDes16::NumUC()
1.3257 +*/
1.3258 + {
1.3259 +
1.3260 + VA_LIST list;
1.3261 + VA_START(list,aFmt);
1.3262 + // coverity[uninit_use_in_call]
1.3263 + FormatList(aFmt,list);
1.3264 + }
1.3265 +
1.3266 +EXPORT_C void TDes16::FormatList(const TDesC16 &aFmt,VA_LIST aList)
1.3267 +/**
1.3268 +Formats and copies text into this descriptor, replacing any existing data.
1.3269 +
1.3270 +The length of this descriptor is set to reflect the new data.
1.3271 +
1.3272 +The behaviour of this function is the same as Format(). In practice, it is
1.3273 +better and easier to use Format(), passing a variable number of arguments
1.3274 +as required by the format string.
1.3275 +
1.3276 +@param aFmt The descriptor containing the format string.
1.3277 +@param aList A pointer to an argument list.
1.3278 +
1.3279 +@see TDes16::Format()
1.3280 +@see VA_LIST
1.3281 +*/
1.3282 + {
1.3283 +
1.3284 + Zero();
1.3285 + AppendFormatList(aFmt,aList);
1.3286 + }
1.3287 +
1.3288 +EXPORT_C void TDes16::AppendFormat(TRefByValue<const TDesC16> aFmt,TDes16Overflow *aOverflowHandler,...)
1.3289 +/**
1.3290 +Formats and appends text onto the end of this descriptor's data.
1.3291 +
1.3292 +The length of this descriptor is incremented to reflect the new content.
1.3293 +
1.3294 +The function takes a format string and a variable number of arguments.
1.3295 +The format string contains literal text, embedded with directives,
1.3296 +for converting the trailing list of arguments into text.
1.3297 +
1.3298 +The embedded directives are character sequences prefixed with the '%' character.
1.3299 +The literal text is simply copied into this descriptor unaltered while
1.3300 +the '%' directives are used to convert successive arguments from the
1.3301 +trailing list. See the description of the Format() function.
1.3302 +
1.3303 +Literal text is appended on a character by character basis.
1.3304 +If it results in the length of this descriptor exceeding its maximum length,
1.3305 +then the function:
1.3306 +
1.3307 +1. calls the Overflow() member function of the overflow handler, if an overflow
1.3308 + handler is supplied
1.3309 +2 raises a USER 11 panic, if no overflow handler is supplied.
1.3310 +
1.3311 +As much literal text as possible will have been copied into this descriptor
1.3312 +and this descriptor will have reached its maximum length.
1.3313 +
1.3314 +Text converted from a trailing argument is appended as a complete string.
1.3315 +If an attempt to append this string fails because the resulting length
1.3316 +of this descriptor would exceed its maximum length, then the function:
1.3317 +
1.3318 +1. calls the Overflow() member function of the overflow handler, if an overflow
1.3319 + handler is supplied
1.3320 +
1.3321 +2 raises a USER 11 panic, if no overflow handler is supplied.
1.3322 +
1.3323 +None of the generated text is appended and length of this descriptor
1.3324 +may be less than the maximum.
1.3325 +
1.3326 +@param aFmt The 16-bit non-modifiable descriptor containing the
1.3327 + format string. The TRefByValue class provides a
1.3328 + constructor which takes a TDesC16 type.
1.3329 +
1.3330 +@param aOverflowHandler A pointer to the overflow handler.
1.3331 +
1.3332 +@param ... A variable number of arguments to be converted to text
1.3333 + as dictated by the format string.
1.3334 +
1.3335 +@panic USER 11 if the length of the descriptor exceeds its maximum length and
1.3336 + no overflow handler has been supplied.
1.3337 +@panic USER 12 if the format string has incorrect syntax.
1.3338 +
1.3339 +@see TDes16::Format()
1.3340 +@see TDes16Overflow::Overflow()
1.3341 +*/
1.3342 + {
1.3343 +
1.3344 + VA_LIST list;
1.3345 + VA_START(list, aOverflowHandler);
1.3346 + // coverity[uninit_use_in_call]
1.3347 + AppendFormatList(aFmt,list,aOverflowHandler);
1.3348 + }
1.3349 +
1.3350 +EXPORT_C void TDes16::AppendFormat(TRefByValue<const TDesC16> aFmt,...)
1.3351 +/**
1.3352 +Formats and appends text onto the end of this descriptor's data.
1.3353 +
1.3354 +The length of this descriptor is incremented to reflect the new content.
1.3355 +
1.3356 +The function takes a format string and a variable number of arguments.
1.3357 +The format string contains literal text, embedded with directives,
1.3358 +for converting the trailing list of arguments into text.
1.3359 +
1.3360 +The embedded directives are character sequences prefixed with the '%' character.
1.3361 +The literal text is simply copied into this descriptor unaltered while
1.3362 +the '%' directives are used to convert successive arguments from the
1.3363 +trailing list. See the description of the Format() function.
1.3364 +
1.3365 +Literal text is appended on a character by character basis.
1.3366 +
1.3367 +Text converted from a trailing argument is appended as a complete string.
1.3368 +
1.3369 +@param aFmt The 16-bit non-modifiable descriptor containing the
1.3370 + format string. The TRefByValue class provides a
1.3371 + constructor which takes a TDesC16 type.
1.3372 +
1.3373 +@param ... A variable number of arguments to be converted to text
1.3374 + as dictated by the format string.
1.3375 +
1.3376 +@panic USER 11 if the resulting length of text in this descriptor exceeds
1.3377 + the descriptor's maximum length.
1.3378 +@panic USER 12 if the format string has incorrect syntax.
1.3379 +
1.3380 +@see TDes16::Format()
1.3381 +*/
1.3382 + {
1.3383 +
1.3384 + VA_LIST list;
1.3385 + VA_START(list,aFmt);
1.3386 + AppendFormatList(aFmt,list);
1.3387 + }
1.3388 +
1.3389 +#if !defined(__DES16_MACHINE_CODED__) | defined(__EABI_CTORS__)
1.3390 +EXPORT_C TPtrC16::TPtrC16()
1.3391 + : TDesC16(EPtrC,0),iPtr(0)
1.3392 +/**
1.3393 +Constructs an empty 16-bit non-modifiable pointer descriptor.
1.3394 +
1.3395 +It represents no data and its length is zero.
1.3396 +
1.3397 +The non-modifiable pointer descriptor can, subsequently, be set to represent
1.3398 +data.
1.3399 +
1.3400 +@see TPtrC16::Set()
1.3401 +*/
1.3402 + {}
1.3403 +
1.3404 +EXPORT_C TPtrC16::TPtrC16(const TDesC16 &aDes)
1.3405 + : TDesC16(EPtrC,aDes.Length()),iPtr(aDes.Ptr())
1.3406 +/**
1.3407 +Constructs the 16-bit non-modifiable pointer descriptor from any existing
1.3408 +descriptor.
1.3409 +
1.3410 +It is set to point to the same data and is given the same length as the source
1.3411 +descriptor.
1.3412 +
1.3413 +@param aDes A reference to a 16-bit non-modifiable descriptor.
1.3414 +*/
1.3415 + {}
1.3416 +#endif
1.3417 +
1.3418 +#if !defined(__DES16_MACHINE_CODED_HWORD__) | defined(__EABI_CTORS__)
1.3419 +EXPORT_C TPtrC16::TPtrC16(const TUint16 *aString)
1.3420 + : TDesC16(EPtrC,STRING_LENGTH_16(aString)),iPtr(aString)
1.3421 +/**
1.3422 +Constructs the 16-bit non-modifiable pointer descriptor to point to a zero
1.3423 +terminated string, whether in RAM or ROM.
1.3424 +
1.3425 +The length of the descriptor is set to the length of the zero terminated string,
1.3426 +excluding the zero terminator.
1.3427 +
1.3428 +@param aString A pointer to a zero terminated string.
1.3429 +*/
1.3430 + {
1.3431 + __CHECK_ALIGNMENT(aString,ETDesC16ConstructCString);
1.3432 + }
1.3433 +#endif
1.3434 +
1.3435 +#if !defined(__DES16_MACHINE_CODED__) | defined(__EABI_CTORS__)
1.3436 +EXPORT_C TPtrC16::TPtrC16(const TUint16 *aBuf,TInt aLength)
1.3437 + : TDesC16(EPtrC,aLength),iPtr(aBuf)
1.3438 +/**
1.3439 +Constructs the 16-bit non-modifiable pointer descriptor to point to the
1.3440 +specified location in memory, whether in RAM or ROM.
1.3441 +
1.3442 +The length of the descriptor is set to the specified length.
1.3443 +
1.3444 +@param aBuf A pointer to the location that the descriptor is to represent.
1.3445 +@param aLength The length of the descriptor.This value must be non-negative.
1.3446 +
1.3447 +@panic USER 17 if aLength is negative.
1.3448 +*/
1.3449 + {
1.3450 + __ASSERT_ALWAYS(aLength>=0,Panic(ETDes16LengthNegative));
1.3451 + __CHECK_ALIGNMENT(aBuf,ETDesC16ConstructBufLength);
1.3452 + }
1.3453 +
1.3454 +EXPORT_C TPtr16::TPtr16(TUint16 *aBuf,TInt aMaxLength)
1.3455 + : TDes16(EPtr,0,aMaxLength),iPtr(aBuf)
1.3456 +/**
1.3457 +Constructs the 16-bit modifiable pointer descriptor to point to the specified
1.3458 +location in memory, whether in RAM or ROM.
1.3459 +
1.3460 +The length of the descriptor is set to zero, and its maximum length is set to
1.3461 +the specified value.
1.3462 +
1.3463 +@param aBuf A pointer to the location that the descriptor is to represent.
1.3464 +@param aMaxLength The maximum length of the descriptor.
1.3465 +
1.3466 +@panic USER 18 if aMaxLength is negative.
1.3467 +*/
1.3468 + {
1.3469 + __ASSERT_ALWAYS(aMaxLength>=0,Panic(ETDes16MaxLengthNegative));
1.3470 + __CHECK_ALIGNMENT(aBuf,ETDesC16ConstructBufLengthMax);
1.3471 + }
1.3472 +
1.3473 +EXPORT_C TPtr16::TPtr16(TUint16 *aBuf,TInt aLength,TInt aMaxLength)
1.3474 + : TDes16(EPtr,aLength,aMaxLength),iPtr(aBuf)
1.3475 +/**
1.3476 +Constructs the 16-bit modifiable pointer descriptor to point to the specified
1.3477 +location in memory, whether in RAM or ROM.
1.3478 +
1.3479 +The length of the descriptor and its maximum length are set to the specified
1.3480 +values.
1.3481 +
1.3482 +@param aBuf A pointer to the location that the descriptor is to represent.
1.3483 +@param aLength The length of the descriptor.
1.3484 +@param aMaxLength The maximum length of the descriptor.
1.3485 +
1.3486 +@panic USER 8 if aLength is negative, or is greater than the descriptor's
1.3487 + maximum length,
1.3488 +
1.3489 +@panic USER 18 if aMaxLength is negative.
1.3490 +*/
1.3491 + {
1.3492 + __ASSERT_ALWAYS(aMaxLength>=0,Panic(ETDes16MaxLengthNegative));
1.3493 + __ASSERT_ALWAYS(TUint(aLength)<=TUint(aMaxLength),Panic(ETDes16LengthOutOfRange));
1.3494 + __CHECK_ALIGNMENT(aBuf,ETDesC16ConstructBufLengthMax);
1.3495 + }
1.3496 +
1.3497 +EXPORT_C TBufBase16::TBufBase16(TInt aMaxLength)
1.3498 + :TDes16(EBuf,0,aMaxLength)
1.3499 + {
1.3500 + __ASSERT_DEBUG(aMaxLength>=0,Panic(ETDes16MaxLengthNegative));
1.3501 + }
1.3502 +
1.3503 +EXPORT_C TBufBase16::TBufBase16(TInt aLength,TInt aMaxLength)
1.3504 + :TDes16(EBuf,aLength,aMaxLength)
1.3505 + {
1.3506 + __ASSERT_DEBUG(aMaxLength>=0,Panic(ETDes16MaxLengthNegative));
1.3507 + __ASSERT_ALWAYS(TUint(aLength)<=TUint(aMaxLength),Panic(ETDes16LengthOutOfRange));
1.3508 + }
1.3509 +#endif
1.3510 +
1.3511 +#if !defined( __DES16_MACHINE_CODED_HWORD__) | defined(__EABI_CTORS__)
1.3512 +EXPORT_C TBufBase16::TBufBase16(const TUint16* aString,TInt aMaxLength)
1.3513 + :TDes16(EBuf,0,aMaxLength)
1.3514 + {
1.3515 + __ASSERT_DEBUG(aMaxLength>=0,Panic(ETDes16MaxLengthNegative));
1.3516 + Copy(aString);
1.3517 + }
1.3518 +#endif
1.3519 +
1.3520 +#if !defined( __DES16_MACHINE_CODED__) | defined(__EABI_CTORS__)
1.3521 +EXPORT_C TBufBase16::TBufBase16(const TDesC16& aDes,TInt aMaxLength)
1.3522 + :TDes16(EBuf,0,aMaxLength)
1.3523 + {
1.3524 + __ASSERT_DEBUG(aMaxLength>=0,Panic(ETDes16MaxLengthNegative));
1.3525 + Copy(aDes);
1.3526 + }
1.3527 +#endif
1.3528 +
1.3529 +EXPORT_C void TDesC16::__DbgTestInvariant() const
1.3530 +//
1.3531 +// Test that the class obeys its invariant.
1.3532 +//
1.3533 + {
1.3534 +
1.3535 +#if defined(_DEBUG)
1.3536 + switch (Type())
1.3537 + {
1.3538 + case EBufC:
1.3539 + case EPtrC:
1.3540 + case EPtr:
1.3541 + case EBuf:
1.3542 + case EBufCPtr:
1.3543 + break;
1.3544 + default:
1.3545 + User::Invariant();
1.3546 + }
1.3547 + if (Ptr() != NULL) // TPtr and TPtrC can be null
1.3548 + __CHECK_ALIGNMENT(Ptr(),ETDesC16Invariant);
1.3549 +#endif
1.3550 + }
1.3551 +
1.3552 +EXPORT_C void TPtrC16::__DbgTestInvariant() const
1.3553 +//
1.3554 +// Test that the class obeys its invariant.
1.3555 +//
1.3556 + {
1.3557 +
1.3558 +#if defined(_DEBUG)
1.3559 + TDesC16::__DbgTestInvariant(); // Test base class
1.3560 + if (Type()!=EPtrC)
1.3561 + User::Invariant();
1.3562 +#endif
1.3563 + }
1.3564 +
1.3565 +EXPORT_C void TDes16::__DbgTestInvariant() const
1.3566 +//
1.3567 +// Test that the class obeys its invariant.
1.3568 +//
1.3569 + {
1.3570 +
1.3571 +#if defined(_DEBUG)
1.3572 + TDesC16::__DbgTestInvariant(); // Test base class
1.3573 + if (Length()>MaxLength() || !(Type()==EPtr || Type()==EBufCPtr || Type()==EBuf))
1.3574 + User::Invariant();
1.3575 +#endif
1.3576 + }
1.3577 +
1.3578 +EXPORT_C void HBufC16::__DbgTestInvariant() const
1.3579 +//
1.3580 +// Test that the class obeys its invariant.
1.3581 +//
1.3582 + {
1.3583 +
1.3584 +#if defined(_DEBUG)
1.3585 + TDesC16::__DbgTestInvariant(); // Test base class
1.3586 + if (Length()>(TInt)(STD_CLASS::AllocLen(this)-sizeof(TDesC16)) || Type()!=EBufC)
1.3587 + User::Invariant();
1.3588 +#endif
1.3589 + }
1.3590 +
1.3591 +EXPORT_C void TPtr16::__DbgTestInvariant() const
1.3592 +//
1.3593 +// Test that the class obeys its invariant.
1.3594 +//
1.3595 + {
1.3596 +
1.3597 +#if defined(_DEBUG)
1.3598 + TDes16::__DbgTestInvariant(); // Test base class
1.3599 + if (!(Type()==EPtr || Type()==EBufCPtr))
1.3600 + User::Invariant();
1.3601 +#endif
1.3602 + }
1.3603 +
1.3604 +/** Collapse all characters from 16 to 8 bits
1.3605 +
1.3606 +@return 8-bit pointer descriptor to transformed text
1.3607 +*/
1.3608 +EXPORT_C TPtr8 TDes16::Collapse()
1.3609 + {
1.3610 + TInt l = Length();
1.3611 + TInt ml = MaxLength();
1.3612 + TText8* d = (TText8*)Ptr();
1.3613 + TText8* d0 = d;
1.3614 + const TText16* s = (const TText16*)d;
1.3615 + const TText16* sE = s + l;
1.3616 + while (s < sE)
1.3617 + *d++ = (TText8)*s++;
1.3618 + return TPtr8(d0, l, ml*sizeof(TText));
1.3619 + }
1.3620 +
1.3621 +// Truncate literal string to fit into descriptor
1.3622 +EXPORT_C void TDes16IgnoreOverflow::Overflow(TDes16& /*aDes*/)
1.3623 + {}
1.3624 +
1.3625 +#ifndef __KERNEL_MODE__
1.3626 +
1.3627 +/**
1.3628 +Default constructor.
1.3629 +
1.3630 +Constructs a zero-length 16-bit resizable buffer descriptor.
1.3631 +
1.3632 +Note that the object owns no allocated memory.
1.3633 +*/
1.3634 +EXPORT_C RBuf16::RBuf16()
1.3635 + :TDes16(EPtr,0,0),iEPtrType(NULL)
1.3636 + {
1.3637 + // Zero-length RBuf16 is of type EPtr with NULL pointer.
1.3638 + }
1.3639 +
1.3640 +
1.3641 +
1.3642 +
1.3643 +/**
1.3644 +Constructor.
1.3645 +
1.3646 +Constructs a 16-bit resizable buffer descriptor, transferring ownership of the
1.3647 +specified heap descriptor to this object.
1.3648 +
1.3649 +@param aHBuf The heap descriptor to be transferred to this object. This pointer
1.3650 + can be NULL, which means that a zero length 16-bit resizable
1.3651 + buffer descriptor is constructed, and the object will not own any
1.3652 + allocated memory.
1.3653 +*/
1.3654 +EXPORT_C RBuf16::RBuf16(HBufC16* aHBuf)
1.3655 + {
1.3656 + if(aHBuf)
1.3657 + //Create EBufCPtr type descriptor that points to aHBuf
1.3658 + new(this) TPtr16(aHBuf->Des());
1.3659 + else
1.3660 + //Create zero-length RBuf16. It is EPtr type of descriptor that points to NULL.
1.3661 + new(this) RBuf16();
1.3662 + }
1.3663 +
1.3664 +
1.3665 +
1.3666 +
1.3667 +/**
1.3668 +Protected constructor.
1.3669 +*/
1.3670 +EXPORT_C RBuf16::RBuf16(TInt aType,TInt aLength,TInt aMaxLength)
1.3671 + :TDes16(aType,aLength,aMaxLength)
1.3672 + {
1.3673 + }
1.3674 +
1.3675 +
1.3676 +
1.3677 +
1.3678 +/**
1.3679 +Transfers ownership of the specified 16-bit resizable buffer descriptor's
1.3680 +buffer to this object.
1.3681 +
1.3682 +Note that the function assumes that this descriptor does not already own any
1.3683 +allocated memory. It does not check, nor does it free any pre-existing owned
1.3684 +allocated memory. If this descriptor does already own allocated memory,
1.3685 +RBuf16::Close() should be invoked on this descriptor before this function is
1.3686 +invoked.
1.3687 +
1.3688 +@param aRBuf The source 16-bit resizable buffer. The ownership of this
1.3689 + object's buffer is to be transferred.
1.3690 +
1.3691 +@see RBuf16::Close()
1.3692 +*/
1.3693 +EXPORT_C void RBuf16::Assign(const RBuf16& aRBuf)
1.3694 + {
1.3695 + Mem::Copy(this, &aRBuf, sizeof(*this));
1.3696 + __TEST_INVARIANT;
1.3697 + }
1.3698 +
1.3699 +
1.3700 +
1.3701 +
1.3702 +/**
1.3703 +Assigns ownership of the specified allocated memory to this object.
1.3704 +
1.3705 +The allocated memory forms the buffer for this descriptor. The current length
1.3706 +of the descriptor is set to zero.
1.3707 +
1.3708 +Note that the function assumes that this descriptor does not already own any
1.3709 +allocated memory. It does not check, nor does it free any pre-existing owned
1.3710 +allocated memory. If this descriptor does already own allocated memory,
1.3711 +RBuf16::Close() should be invoked on this descriptor before this function is
1.3712 +invoked.
1.3713 +
1.3714 +@param aHeapCell The allocated memory to be assigned to this object. This
1.3715 + pointer can be NULL, which means that a zero length 16-bit
1.3716 + resizable buffer descriptor is created.
1.3717 +@param aMaxLength The maximum length of the descriptor.
1.3718 +
1.3719 +@panic USER 8 If the specified maximum length is greater then the size of
1.3720 + the allocated heap cell, or the specified maximum length
1.3721 + is NOT zero when the pointer to the heap cell is NULL.
1.3722 +
1.3723 +@see TDesC16::Length()
1.3724 +@see TDes16::MaxLength()
1.3725 +@see RBuf16::Close()
1.3726 +*/
1.3727 +EXPORT_C void RBuf16::Assign(TUint16 *aHeapCell,TInt aMaxLength)
1.3728 + {
1.3729 + Assign(aHeapCell,0,aMaxLength);
1.3730 + }
1.3731 +
1.3732 +
1.3733 +
1.3734 +
1.3735 +/**
1.3736 +Assigns ownership of the specified allocated memory to this object.
1.3737 +
1.3738 +The allocated memory forms the buffer for this descriptor. The current length
1.3739 +of the descriptor is set to the value of the second parameter.
1.3740 +
1.3741 +Note that the function assumes that this descriptor does not already own any
1.3742 +allocated memory. It does not check, nor does it free any pre-existing owned
1.3743 +allocated memory. If this descriptor does already own allocated memory,
1.3744 +RBuf16::Close() should be invoked on this descriptor before this function is
1.3745 +invoked.
1.3746 +
1.3747 +@param aHeapCell The allocated memory to be assigned to this object.
1.3748 +@param aLength The length of the descriptor.
1.3749 +@param aMaxLength The maximum length of the descriptor.
1.3750 +
1.3751 +@panic USER 8 If the specified maximum length is greater then the size of
1.3752 + the allocated heap cell, or the specified length is greater then
1.3753 + the specified maximum length, or the specified maximum length
1.3754 + is NOT zero when the pointer to the heap cell is NULL.
1.3755 +
1.3756 +@see TDesC16::Length()
1.3757 +@see TDes16::MaxLength()
1.3758 +@see RBuf16::Close()
1.3759 +*/
1.3760 +EXPORT_C void RBuf16::Assign(TUint16 *aHeapCell,TInt aLength,TInt aMaxLength)
1.3761 + {
1.3762 + __ASSERT_ALWAYS(aLength<=aMaxLength, Panic(ETDes16LengthOutOfRange));
1.3763 + if(aHeapCell)
1.3764 + {
1.3765 + __ASSERT_ALWAYS(User::AllocLen(aHeapCell) >= aMaxLength * (TInt)sizeof(TUint16), Panic(ETDes16LengthOutOfRange));
1.3766 + //Create EPtr type descriptor that points to aHeapCell
1.3767 + new(this) TPtr16(aHeapCell,aLength,aMaxLength);
1.3768 + }
1.3769 + else
1.3770 + {
1.3771 + __ASSERT_ALWAYS(aMaxLength == 0, Panic(ETDes16LengthOutOfRange));
1.3772 + //Create zero-length RBuf. It is EPtr type of descriptor that points to NULL.
1.3773 + new(this) RBuf16();
1.3774 + }
1.3775 + __TEST_INVARIANT;
1.3776 + }
1.3777 +
1.3778 +
1.3779 +
1.3780 +
1.3781 +/**
1.3782 +Transfers ownership of the specified heap descriptor to this object.
1.3783 +
1.3784 +Note that the function assumes that this descriptor does not already own any
1.3785 +allocated memory. It does not check, nor does it free any pre-existing owned
1.3786 +allocated memory. If this descriptor does already own allocated memory,
1.3787 +RBuf16::Close() should be invoked on this descriptor before this function is
1.3788 +invoked.
1.3789 +
1.3790 +@param aHBuf The heap descriptor to be transferred to this object.
1.3791 + This pointer can be NULL, which means that a zero length
1.3792 + 16-bit resizable buffer descriptor is created.
1.3793 +
1.3794 +@see RBuf16::Close()
1.3795 +*/
1.3796 +EXPORT_C void RBuf16::Assign(HBufC16* aHBuf)
1.3797 + {
1.3798 + new(this) RBuf16(aHBuf);
1.3799 + }
1.3800 +
1.3801 +
1.3802 +
1.3803 +
1.3804 +/**
1.3805 +Swaps the content of two 16-bit resizable buffer descriptors.
1.3806 +
1.3807 +@param aRBuf The 16-bit resizable buffer descriptor whose contents are to be
1.3808 + swapped with this one.
1.3809 +*/
1.3810 +EXPORT_C void RBuf16::Swap(RBuf16& aRBuf)
1.3811 + {
1.3812 + Mem::Swap(this,&aRBuf,sizeof(*this));
1.3813 + }
1.3814 +
1.3815 +
1.3816 +
1.3817 +
1.3818 +/**
1.3819 +Creates a 16-bit resizable buffer descriptor.
1.3820 +
1.3821 +The function allocates sufficient memory to contain descriptor data up to
1.3822 +the specified maximum length.
1.3823 +
1.3824 +The current length of the descriptor is set to zero. The maximum length of
1.3825 +the descriptor is set to the specified value.
1.3826 +
1.3827 +Note that the function assumes that this descriptor does not already own any
1.3828 +allocated memory. It does not check, nor does it free any pre-existing owned
1.3829 +allocated memory. If this descriptor does already own allocated memory,
1.3830 +RBuf16::Close() should be invoked on this descriptor before this function is
1.3831 +invoked.
1.3832 +
1.3833 +@param aMaxLength The maximum length of the descriptor.
1.3834 +
1.3835 +@return KErrNone, if successful; KErrNoMemory, if there is insufficient memory.
1.3836 +
1.3837 +@see TDesC16::Length()
1.3838 +@see TDes16::MaxLength()
1.3839 +@see RBuf16::Close()
1.3840 +*/
1.3841 +EXPORT_C TInt RBuf16::Create(TInt aMaxLength)
1.3842 + {
1.3843 + if (aMaxLength)
1.3844 + {
1.3845 + //Allocate memory
1.3846 + TUint16* buf=(TUint16*)User::Alloc(aMaxLength*sizeof(TUint16));
1.3847 + if(!buf) return KErrNoMemory;
1.3848 + iEPtrType = buf;
1.3849 + }
1.3850 + else
1.3851 + iEPtrType = NULL; //Zero-length descriptor.
1.3852 +
1.3853 +
1.3854 + //Create EPtr type descriptor.
1.3855 + new(this) RBuf16(EPtr,0,aMaxLength);
1.3856 + __TEST_INVARIANT;
1.3857 + return KErrNone;
1.3858 + }
1.3859 +
1.3860 +
1.3861 +
1.3862 +
1.3863 +/**
1.3864 +Creates 16-bit resizable buffer descriptor, and leaves on failure.
1.3865 +
1.3866 +The function allocates sufficient memory to contain descriptor data up to
1.3867 +the specified maximum length.
1.3868 +
1.3869 +The current length of the descriptor is set to zero. The maximum length of
1.3870 +the descriptor is set to the specified value.
1.3871 +
1.3872 +Note that the function assumes that this descriptor does not already own any
1.3873 +allocated memory. It does not check, nor does it free any pre-existing owned
1.3874 +allocated memory. If this descriptor does already own allocated memory,
1.3875 +RBuf16::Close() should be invoked on this descriptor before this function is
1.3876 +invoked.
1.3877 +
1.3878 +@param aMaxLength The maximum length of the descriptor.
1.3879 +
1.3880 +@leave KErrNoMemory If there is insufficient memory.
1.3881 +
1.3882 +@see TDesC16::Length()
1.3883 +@see TDes16::MaxLength()
1.3884 +@see RBuf16::Close()
1.3885 +*/
1.3886 +EXPORT_C void RBuf16::CreateL(TInt aMaxLength)
1.3887 + {
1.3888 + User::LeaveIfError(Create(aMaxLength));
1.3889 + }
1.3890 +
1.3891 +
1.3892 +
1.3893 +
1.3894 +/**
1.3895 +Creates a 16-bit resizable buffer descriptor.
1.3896 +
1.3897 +The function allocates sufficient memory to contain descriptor data up to
1.3898 +the specified maximum length.
1.3899 +
1.3900 +Both the current length and the maximum length of the descriptor are set to
1.3901 +the specified value.
1.3902 +
1.3903 +Note that the function assumes that this descriptor does not already own any
1.3904 +allocated memory. It does not check, nor does it free any pre-existing owned
1.3905 +allocated memory. If this descriptor does already own allocated memory,
1.3906 +RBuf16::Close() should be invoked on this descriptor before this function is
1.3907 +invoked.
1.3908 +
1.3909 +@param aMaxLength The length and the maximum length of the descriptor.
1.3910 +
1.3911 +@return KErrNone, if successful; KErrNoMemory, if there is insufficient memory.
1.3912 +
1.3913 +@see RBuf16::Close()
1.3914 +*/
1.3915 +EXPORT_C TInt RBuf16::CreateMax(TInt aMaxLength)
1.3916 + {
1.3917 + TInt err=Create(aMaxLength);
1.3918 + if(err==KErrNone)
1.3919 + SetMax();
1.3920 + return err;
1.3921 + }
1.3922 +
1.3923 +
1.3924 +
1.3925 +
1.3926 +/**
1.3927 +Creates a 16-bit resizable buffer descriptor, and leaves on failure.
1.3928 +
1.3929 +The function allocates sufficient memory to contain descriptor data up to
1.3930 +the specified maximum length.
1.3931 +
1.3932 +Both the current length and the maximum length of the descriptor are set to
1.3933 +the specified value.
1.3934 +
1.3935 +Note that the function assumes that this descriptor does not already own any
1.3936 +allocated memory. It does not check, nor does it free any pre-existing owned
1.3937 +allocated memory. If this descriptor does already own allocated memory,
1.3938 +RBuf16::Close() should be invoked on this descriptor before this function is
1.3939 +invoked.
1.3940 +
1.3941 +@param aMaxLength The length and the maximum length of the descriptor.
1.3942 +
1.3943 +@leave KErrNoMemory If there is insufficient memory.
1.3944 +
1.3945 +@see TDesC16::Length()
1.3946 +@see TDes16::MaxLength()
1.3947 +@see RBuf16::Close()
1.3948 +*/
1.3949 +EXPORT_C void RBuf16::CreateMaxL(TInt aMaxLength)
1.3950 + {
1.3951 + User::LeaveIfError(CreateMax(aMaxLength));
1.3952 + }
1.3953 +
1.3954 +
1.3955 +
1.3956 +
1.3957 +/**
1.3958 +Creates a 16-bit resizable buffer descriptor to contain a copy of the
1.3959 +specified (source) descriptor.
1.3960 +
1.3961 +The function allocates sufficient memory so that this descriptor's maximum
1.3962 +length is the same as the length of the source descriptor. Both the current
1.3963 +length and the maximum length of this descriptor are set to
1.3964 +the length of the source descriptor.
1.3965 +
1.3966 +The data contained in the source descriptor is copied into this
1.3967 +descriptor.
1.3968 +
1.3969 +Note that the function assumes that this descriptor does not
1.3970 +already own any allocated memory. It does not check, nor does it free any
1.3971 +pre-existing owned allocated memory. If this descriptor does already own
1.3972 +allocated memory, RBuf16::Close() should be invoked on this descriptor before
1.3973 +this function is invoked.
1.3974 +
1.3975 +@param aDes Source descriptor to be copied into this object.
1.3976 +
1.3977 +@return KErrNone, if successful; KErrNoMemory, if there is insufficient memory.
1.3978 +
1.3979 +@see TDesC16::Length()
1.3980 +@see TDes16::MaxLength()
1.3981 +@see TDes16::Copy()
1.3982 +@see RBuf16::Close()
1.3983 +*/
1.3984 +EXPORT_C TInt RBuf16::Create(const TDesC16& aDes)
1.3985 + {
1.3986 + return Create(aDes,aDes.Length());
1.3987 + }
1.3988 +
1.3989 +
1.3990 +
1.3991 +
1.3992 +
1.3993 +/**
1.3994 +Creates a 16-bit resizable buffer descriptor to contain a copy of the specified
1.3995 +(source) descriptor, and leaves on failure.
1.3996 +
1.3997 +The function allocates sufficient memory so that this descriptor's maximum
1.3998 +length is the same as the length of the source descriptor.Both the current
1.3999 +length and the maximum length of this descriptor are set to the length
1.4000 +of the source descriptor.
1.4001 +
1.4002 +The data contained in the source descriptor is copied into this descriptor.
1.4003 +
1.4004 +Note that the function assumes that this descriptor does not already own any
1.4005 +allocated memory. It does not check, nor does it free any
1.4006 +pre-existing owned allocated memory. If this descriptor does already own
1.4007 +allocated memory, RBuf16::Close() should be invoked on this descriptor before
1.4008 +this function is invoked.
1.4009 +
1.4010 +@param aDes Source descriptor to be copied into this object.
1.4011 +
1.4012 +@leave KErrNoMemory If there is insufficient memory.
1.4013 +
1.4014 +@see TDesC16::Length()
1.4015 +@see TDes16::MaxLength()
1.4016 +@see TDes16::Copy()
1.4017 +@see RBuf16::Close()
1.4018 +*/
1.4019 +EXPORT_C void RBuf16::CreateL(const TDesC16& aDes)
1.4020 + {
1.4021 + CreateL(aDes,aDes.Length());
1.4022 + }
1.4023 +
1.4024 +
1.4025 +
1.4026 +
1.4027 +/**
1.4028 +Creates a 16-bit resizable buffer descriptor to contain a copy of the
1.4029 +specified (source) descriptor.
1.4030 +
1.4031 +The function allocates sufficient memory so that this descriptor's maximum length
1.4032 +is the same as the value of the aMaxLength parameter.
1.4033 +
1.4034 +The data contained in the source descriptor is copied into this descriptor.
1.4035 +The length of data copied is either
1.4036 +
1.4037 +- the length of the source descriptor aDes
1.4038 +
1.4039 +or
1.4040 +
1.4041 +- the value of the aMaxLength parameter
1.4042 +
1.4043 +whichever is the smaller value. The current length of this descriptor is also
1.4044 +set to the smaller value.
1.4045 +
1.4046 +Note that the function assumes that this descriptor does not already own any
1.4047 +allocated memory. It does not check, nor does it free any pre-existing owned
1.4048 +allocated memory. If this descriptor does already own allocated memory,
1.4049 +RBuf16::Close() should be invoked on this descriptor before this function is
1.4050 +invoked.
1.4051 +
1.4052 +@param aDes Source descriptor to be copied into this object.
1.4053 +
1.4054 +@param aMaxLength The maximum length of this descriptor.
1.4055 +
1.4056 +@return KErrNone, if successful; KErrNoMemory, if there is insufficient memory.
1.4057 +
1.4058 +@see TDesC16::Length()
1.4059 +@see TDes16::MaxLength()
1.4060 +@see TDes16::Copy()
1.4061 +@see RBuf16::Close()
1.4062 +*/
1.4063 +EXPORT_C TInt RBuf16::Create(const TDesC16& aDes,TInt aMaxLength)
1.4064 + {
1.4065 + TInt err=Create(aMaxLength);
1.4066 + if(err==KErrNone)
1.4067 + Copy(aDes.Left(aMaxLength));
1.4068 + return err;
1.4069 + }
1.4070 +
1.4071 +
1.4072 +
1.4073 +
1.4074 +/**
1.4075 +Creates a 16-bit resizable buffer descriptor to contain a copy of the specified
1.4076 +(source) descriptor, and leaves on failure.
1.4077 +
1.4078 +The function allocates sufficient memory so that this descriptor's maximum
1.4079 +length is the same as the value of the aMaxLength parameter.
1.4080 +
1.4081 +The data contained in the source descriptor is copied into this descriptor.
1.4082 +The length of data copied is either
1.4083 +
1.4084 +- the length of the source descriptor aDes
1.4085 +
1.4086 +or
1.4087 +
1.4088 +- the value of the aMaxLength parameter
1.4089 +
1.4090 +whichever is the smaller value. The current length of this descriptor is also
1.4091 +set to the smaller value.
1.4092 +
1.4093 +Note that the function assumes that this descriptor does not already own any
1.4094 +allocated memory. It does not check, nor does it free any pre-existing owned
1.4095 +allocated memory. If this descriptor does already own allocated memory,
1.4096 +RBuf16::Close() should be invoked on this descriptor before this function is
1.4097 +invoked.
1.4098 +
1.4099 +@param aDes Source descriptor to be copied into this object.
1.4100 +
1.4101 +@param aMaxLength The maximum length of this descriptor.
1.4102 +
1.4103 +@leave KErrNoMemory If there is insufficient memory.
1.4104 +
1.4105 +@see TDesC16::Length()
1.4106 +@see TDes16::MaxLength()
1.4107 +@see TDes16::Copy()
1.4108 +@see RBuf16::Close()
1.4109 +*/
1.4110 +EXPORT_C void RBuf16::CreateL(const TDesC16& aDes,TInt aMaxLength)
1.4111 + {
1.4112 + CreateL(aMaxLength);
1.4113 + Copy(aDes.Left(aMaxLength));
1.4114 + }
1.4115 +
1.4116 +
1.4117 +
1.4118 +
1.4119 +/**
1.4120 +Resizes this 16-bit resizable buffer descriptor.
1.4121 +
1.4122 +The length and contents of the descriptor are unchanged.
1.4123 +
1.4124 +If the buffer descriptor was created from a zero-length heap descriptor
1.4125 +HBufC, this method might leak memory (the heap descriptor is not freed).
1.4126 +It is possible to avoid this by calling the Close() method prior to ReAlloc(),
1.4127 +but this should be done only in this situation (otherwise the buffer contents
1.4128 +will be lost).
1.4129 +
1.4130 +For example, add
1.4131 +@code
1.4132 + if (desc.MaxLength() == 0) desc.Close();
1.4133 +@endcode
1.4134 +before the call to ReAlloc().
1.4135 +
1.4136 +@param aMaxLength The new maximum length of the descriptor. This can be zero,
1.4137 + which results in a descriptor with zero maximum length and no
1.4138 + allocated memory.
1.4139 +
1.4140 +@return KErrNone, if successful; KErrNoMemory, if there is insufficient memory.
1.4141 +
1.4142 +@panic USER 14 If the new maximum length is less then the current descriptor length.
1.4143 +*/
1.4144 +EXPORT_C TInt RBuf16::ReAlloc(TInt aMaxLength)
1.4145 + {
1.4146 + __ASSERT_ALWAYS(Length()<=aMaxLength, Panic(ETDes16ReAllocTooSmall));
1.4147 + __TEST_INVARIANT;
1.4148 +
1.4149 + if (!aMaxLength) //Reallocation to zero length
1.4150 + {
1.4151 + User::Free(iEPtrType); //Free memory
1.4152 + new (this) RBuf16(); //Create zero-length RBuf
1.4153 + return KErrNone;
1.4154 + }
1.4155 +
1.4156 + if (!iMaxLength) //Reallocation from zero length
1.4157 + return Create(aMaxLength);
1.4158 +
1.4159 + switch(Type())
1.4160 + {
1.4161 + case EPtr:
1.4162 + {
1.4163 + TUint16* buf = (TUint16*)User::ReAlloc(iEPtrType,aMaxLength*sizeof(TUint16));
1.4164 + if(!buf) return KErrNoMemory;
1.4165 + iEPtrType = buf;
1.4166 + iMaxLength = aMaxLength;
1.4167 + break;
1.4168 + }
1.4169 + case EBufCPtr:
1.4170 + {
1.4171 + HBufC16* hbufc = iEBufCPtrType->ReAlloc(aMaxLength);
1.4172 + if(!hbufc) return KErrNoMemory;
1.4173 + Assign(hbufc);
1.4174 + break;
1.4175 + }
1.4176 + }
1.4177 +
1.4178 + __TEST_INVARIANT;
1.4179 + return KErrNone;
1.4180 + }
1.4181 +
1.4182 +
1.4183 +
1.4184 +
1.4185 +/**
1.4186 +Resizes this 16-bit resizable buffer descriptor, leaving on failure.
1.4187 +
1.4188 +The length and contents of the descriptor are unchanged.
1.4189 +
1.4190 +If the buffer descriptor was created from a zero-length heap descriptor
1.4191 +HBufC, this method might leak memory (the heap descriptor is not freed).
1.4192 +It is possible to avoid this by calling the Close() method prior to ReAllocL(),
1.4193 +but this should be done only in this situation (otherwise the buffer contents
1.4194 +will be lost).
1.4195 +
1.4196 +For example, add
1.4197 +@code
1.4198 + if (desc.MaxLength() == 0) desc.Close();
1.4199 +@endcode
1.4200 +before the call to ReAlloc().
1.4201 +
1.4202 +@param aMaxLength The new maximum length of the descriptor. This can be zero,
1.4203 + which results in a descriptor with zero maximum length and no
1.4204 + allocated memory.
1.4205 +
1.4206 +@return KErrNone, if successful; KErrNoMemory, if there is insufficient memory.
1.4207 +
1.4208 +@panic USER 14 If the new maximum length is less then the current descriptor length.
1.4209 +*/
1.4210 +EXPORT_C void RBuf16::ReAllocL(TInt aMaxLength)
1.4211 + {
1.4212 + User::LeaveIfError(ReAlloc(aMaxLength));
1.4213 + }
1.4214 +
1.4215 +
1.4216 +
1.4217 +
1.4218 +/**
1.4219 +Deallocates memory assigned to this object, and re-initializes the object as
1.4220 +a zero-length descriptor.
1.4221 +*/
1.4222 +EXPORT_C void RBuf16::Close()
1.4223 + {
1.4224 + User::Free(iEPtrType);
1.4225 + //Create zero-length RBuf. It is EPtr type of descriptor that points to NULL.
1.4226 + new(this) RBuf16();
1.4227 + }
1.4228 +
1.4229 +
1.4230 +
1.4231 +
1.4232 +/**
1.4233 +Pushes a cleanup item for this object onto the cleanup stack.
1.4234 +
1.4235 +The effect of this is to cause Close() to be called on this 16-bit resizable
1.4236 +buffer descriptor, when CleanupStack::PopAndDestroy() is called at some later time.
1.4237 +
1.4238 +@code
1.4239 +...
1.4240 +RBuf16 x;
1.4241 +....
1.4242 +x.CleanupClosePushL();
1.4243 +...
1.4244 +CleanupStack::PopAndDestroy();
1.4245 +...
1.4246 +@endcode
1.4247 +
1.4248 +@see RBuf16::Close()
1.4249 +*/
1.4250 +EXPORT_C void RBuf16::CleanupClosePushL()
1.4251 + {
1.4252 + ::CleanupClosePushL(*this);
1.4253 + }
1.4254 +
1.4255 +
1.4256 +
1.4257 +
1.4258 +/**
1.4259 +Tests that the class obeys its invariant.
1.4260 +*/
1.4261 +EXPORT_C void RBuf16::__DbgTestInvariant() const
1.4262 + {
1.4263 +#ifdef _DEBUG
1.4264 + TDes16::__DbgTestInvariant();
1.4265 + switch(Type())
1.4266 + {
1.4267 + case EPtr:
1.4268 + if (iEPtrType)
1.4269 + {
1.4270 + __ASSERT_DEBUG(User::AllocLen(iEPtrType) >= iMaxLength*(TInt)sizeof(TUint16), Panic(EInvariantFalse));
1.4271 + }
1.4272 + break;
1.4273 + case EBufCPtr:
1.4274 + iEBufCPtrType->__DbgTestInvariant();
1.4275 + __ASSERT_DEBUG(iEBufCPtrType->Des().MaxLength() == iMaxLength, Panic(EInvariantFalse));
1.4276 + __ASSERT_DEBUG(iEBufCPtrType->Length() == Length(), Panic(EInvariantFalse));
1.4277 + break;
1.4278 + default:
1.4279 + User::Invariant();
1.4280 + }
1.4281 +#endif // _DEBUG
1.4282 + }
1.4283 +
1.4284 +#endif // __KERNEL_MODE__
1.4285 +
1.4286 +
1.4287 +#if defined(__DES16_MACHINE_CODED__) || defined(__EABI__)
1.4288 +GLDEF_C void Des16PanicBadDesType()
1.4289 + {
1.4290 + Panic(ETDes16BadDescriptorType);
1.4291 + }
1.4292 +
1.4293 +GLDEF_C void Des16PanicPosOutOfRange()
1.4294 + {
1.4295 + Panic(ETDes16PosOutOfRange);
1.4296 + }
1.4297 +#endif
1.4298 +
1.4299 +#ifdef __DES16_MACHINE_CODED__
1.4300 +GLDEF_C void Des16PanicLengthNegative()
1.4301 + {
1.4302 + Panic(ETDes16LengthNegative);
1.4303 + }
1.4304 +
1.4305 +GLDEF_C void Des16PanicMaxLengthNegative()
1.4306 + {
1.4307 + Panic(ETDes16MaxLengthNegative);
1.4308 + }
1.4309 +
1.4310 +GLDEF_C void Des16PanicLengthOutOfRange()
1.4311 + {
1.4312 + Panic(ETDes16LengthOutOfRange);
1.4313 + }
1.4314 +
1.4315 +GLDEF_C void Des16PanicDesOverflow()
1.4316 + {
1.4317 + Panic(ETDes16Overflow);
1.4318 + }
1.4319 +
1.4320 +GLDEF_C void Des16PanicDesIndexOutOfRange()
1.4321 + {
1.4322 + Panic(ETDes16IndexOutOfRange);
1.4323 + }
1.4324 +#endif
1.4325 +