1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/ossrv/lowlevellibsandfws/genericusabilitylib/src/lstring16.cpp Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,3498 @@
1.4 +// Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +//
1.18 +
1.19 +#include <e32base.h>
1.20 +#include <estring.h>
1.21 +
1.22 +const TUint KDefaultExpandSize = 16;
1.23 +
1.24 +
1.25 +/**
1.26 +Aligns the supplied capacity to the nearest growth factor
1.27 +
1.28 +For performance reasons the growth factor, KDefaultExpandSizeShift,
1.29 +is expressed as an exponent of 2 so shifting can be used to achieve the
1.30 +alignment.
1.31 +
1.32 +a KDefaultExpandSizeShift value of 4 is equivalent to 16;
1.33 +giving newCapacity = ((newCapacity / 16) + 1) * 16
1.34 +
1.35 +@param aNewCapacity The size to be aligned
1.36 +
1.37 +@return The new, aligned capacity
1.38 +*/
1.39 +static inline TInt AlignCapacity(TInt aNewCapacity)
1.40 + {
1.41 + const TUint KDefaultExpandSizeShift = 4;
1.42 +
1.43 + return (TInt)((((TUint)aNewCapacity >> KDefaultExpandSizeShift) + 1) << KDefaultExpandSizeShift);
1.44 + }
1.45 +
1.46 +/**
1.47 +Guarantees that MaxLength() is greater than or equal to the supplied
1.48 +capacity, reallocating the supplied capacity if necessary.
1.49 +
1.50 +The actual value of MaxLength() after a call may differ from the exact
1.51 +value requested, but if it does differ it will always be greater. This
1.52 +flexibility allows the implementation to manage heap buffers more
1.53 +efficiently.
1.54 +
1.55 +The string descriptor's heap buffer may be reallocated in order to
1.56 +accommodate the new size. As a
1.57 +result, MaxLength() and Ptr() may return different values afterwards,
1.58 +and any existing raw pointers to into the descriptor data may be
1.59 +invalidated.
1.60 +
1.61 +@param aMinRequiredCapacity The minimum value of MaxLength() required
1.62 +
1.63 +@leave KErrNoMemory if the underlying buffer needs to be
1.64 +grown and there are insufficient resources to do so
1.65 +*/
1.66 +void LString16::ReserveL(TInt aMinRequiredCapacity)
1.67 + {
1.68 + if (MaxLength() < aMinRequiredCapacity)
1.69 + {
1.70 + ReAllocL(AlignCapacity(aMinRequiredCapacity));
1.71 + }
1.72 + }
1.73 +
1.74 +
1.75 +/**
1.76 +Guarantees that MaxLength() is greater than or equal to the supplied
1.77 +integer parameter, growing the underlying heap buffer if necessary.
1.78 +
1.79 +The growth is exponential; maxLength *= 1.5
1.80 +This is reported to give an amortised complexity of O(n) when adding
1.81 +n characters.
1.82 +If the required capacity is larger than the expanded size then the
1.83 +required capacity is used instead.
1.84 +
1.85 +The actual value of MaxLength() after a call may differ from the exact
1.86 +value requested, but if it does differ it will always be greater. This
1.87 +flexibility allows the implementation to manage heap buffers more
1.88 +efficiently.
1.89 +
1.90 +@param aRequiredCapacity The minimum value of MaxLength() required
1.91 +
1.92 +@leave KErrNoMemory if the underlying buffer needs to be
1.93 +grown and there are insufficient resources to do so
1.94 +*/
1.95 +void LString16::ReserveCapacityGrowExponentialL(TInt aRequiredCapacity)
1.96 + {
1.97 + //work in unsigned int for the appropriate shift operation
1.98 + TUint max_length = MaxLength();
1.99 + TUint requiredCapacity = aRequiredCapacity;
1.100 +
1.101 + if (max_length < requiredCapacity)
1.102 + {
1.103 + // max_length *= 3/2;
1.104 + max_length = (max_length + (max_length << 1)) >> 1;
1.105 +
1.106 + // take the bigger of the extended buffer or the required capactiy
1.107 + ReAllocL(AlignCapacity((TInt)(max_length > requiredCapacity ? max_length : requiredCapacity)));
1.108 + }
1.109 + }
1.110 +
1.111 +/**
1.112 +Guarantees that free space in the buffer greater than or equal the
1.113 +supplied integer parameter, growing the underlying heap buffer
1.114 +if necessary.
1.115 +
1.116 +@param aRequiredEmptySpace The minimum value of free space required
1.117 +
1.118 +@leave KErrNoMemory if the underlying buffer needs to be
1.119 +grown and there are insufficient resources to do so
1.120 +*/
1.121 +void LString16::ReserveFreeCapacityGrowExponentialL(TInt aRequiredEmptySpace)
1.122 + {
1.123 + ReserveCapacityGrowExponentialL(Length() + aRequiredEmptySpace);
1.124 + }
1.125 +
1.126 +/**
1.127 +Grows the underlying buffer using the exponential growth
1.128 +function. Guarantees that MaxLength() is greater than or
1.129 +equal to 1.5 * the current MaxLength.
1.130 +
1.131 +
1.132 +@leave KErrNoMemory if the underlying buffer needs to be
1.133 +grown and there are insufficient resources to do so
1.134 +*/
1.135 +void LString16::ReserveCapacityGrowExponentialL()
1.136 + {
1.137 + ReserveCapacityGrowExponentialL(MaxLength() + 1);
1.138 + }
1.139 +
1.140 +
1.141 +/**
1.142 +Default constructor.
1.143 +
1.144 +Constructs a zero-length 16-bit resizable string descriptor.
1.145 +
1.146 +Note that the resulting object owns no allocated memory yet. This
1.147 +default constructor never leaves.
1.148 +*/
1.149 +EXPORT_C LString16::LString16()
1.150 + : iReserved(0)
1.151 + {
1.152 + }
1.153 +
1.154 +/**
1.155 +Destructor.
1.156 +
1.157 +Frees any heap-allocated resources owned by this string descriptor. It
1.158 +is safe to rely on this destructor to perform all necessary cleanup;
1.159 +it is not necessary use the cleanup stack or to call Close() manually.
1.160 +
1.161 +@see RBuf16::Close
1.162 +*/
1.163 +EXPORT_C LString16::~LString16()
1.164 + {
1.165 + RBuf16::Close();
1.166 + }
1.167 +
1.168 +/**
1.169 +Constructor to create a 16-bit resizable string descriptor with an
1.170 +initial capacity.
1.171 +
1.172 +The function allocates sufficient memory to contain descriptor data up to
1.173 +the specified initial maximum length.
1.174 +
1.175 +The current length of the descriptor is set to zero. The maximum length of
1.176 +the descriptor is set to the specified value.
1.177 +
1.178 +@param aMaxLength The maximum length of the descriptor.
1.179 +
1.180 +@leave KErrNoMemory If there is insufficient memory.
1.181 +
1.182 +@see RBuf16::CreateL
1.183 +*/
1.184 +EXPORT_C LString16::LString16(TInt aMaxLength)
1.185 + : iReserved(0)
1.186 + {
1.187 + RBuf16::CreateL(aMaxLength);
1.188 + }
1.189 +
1.190 +/**
1.191 +Constructor to create a 16-bit resizable string descriptor from a
1.192 +pre-allocated heap descriptor.
1.193 +
1.194 +Transfers ownership of the specified heap descriptor to this object.
1.195 +
1.196 +@param aHBuf The heap descriptor to be transferred to this object.
1.197 + This pointer can be NULL, which means that a zero length
1.198 + 16-bit resizable string descriptor is created.
1.199 +
1.200 +@see RBuf16::RBuf16(HBufC16*)
1.201 +*/
1.202 +EXPORT_C LString16::LString16(HBufC16* aHBuf)
1.203 + : iReserved(0)
1.204 + {
1.205 + if (aHBuf)
1.206 + RBuf16::Assign (aHBuf);
1.207 + }
1.208 +
1.209 +/**
1.210 +Constructor to create a 16-bit resizable string descriptor from a
1.211 +pre-allocated raw heap buffer.
1.212 +
1.213 +The allocated memory forms the buffer for this string descriptor. The
1.214 +current length of the descriptor is set to zero.
1.215 +
1.216 +@param aHeapCell The allocated memory to be assigned to this object. This
1.217 + pointer can be NULL, which means that a zero length 16-bit
1.218 + resizable buffer descriptor is created.
1.219 +@param aMaxLength The maximum length of the constructed string descriptor.
1.220 +
1.221 +@panic USER 8 If the specified maximum length is greater then the size of
1.222 + the allocated heap cell, or the specified maximum length
1.223 + is NOT zero when the pointer to the heap cell is NULL.
1.224 +
1.225 +@see RBuf16::Assign()
1.226 +*/
1.227 +EXPORT_C LString16::LString16(TUint16* aHeapCell,TInt aMaxLength)
1.228 + : iReserved(0)
1.229 + {
1.230 + RBuf16::Assign(aHeapCell, aMaxLength);
1.231 + }
1.232 +
1.233 +/**
1.234 +Constructor to create a 16-bit resizable string descriptor from a
1.235 +pre-allocated raw heap buffer.
1.236 +
1.237 +The allocated memory forms the buffer for this string descriptor. The
1.238 +current length of the descriptor is set to the value of the second
1.239 +parameter.
1.240 +
1.241 +@param aHeapCell The allocated memory to be assigned to this object.
1.242 +@param aLength The length of the resulting string descriptor.
1.243 +@param aMaxLength The maximum length of the resulting string descriptor.
1.244 +
1.245 +@panic USER 8 If the specified maximum length is greater then the size of
1.246 + the allocated heap cell, or the specified length is greater then
1.247 + the specified maximum length, or the specified maximum length
1.248 + is NOT zero when the pointer to the heap cell is NULL.
1.249 +
1.250 +@see RBuf16::Assign()
1.251 +*/
1.252 +EXPORT_C LString16::LString16(TUint16* aHeapCell,TInt aLength,TInt aMaxLength)
1.253 + : iReserved(0)
1.254 + {
1.255 + RBuf16::Assign(aHeapCell, aLength, aMaxLength);
1.256 + }
1.257 +
1.258 +/**
1.259 +Constructor to create a 16-bit resizable string descriptor to contain
1.260 +a copy of the specified (source) descriptor, or leave on failure.
1.261 +
1.262 +The constructor allocates sufficient memory so that this string
1.263 +descriptor's maximum length is the same as the length of the source
1.264 +descriptor. Both the current length and the maximum length of this
1.265 +string descriptor are set to the length of the source descriptor.
1.266 +
1.267 +The data contained in the source descriptor is copied into this string
1.268 +descriptor.
1.269 +
1.270 +@param aDes Source descriptor to be copied into this object.
1.271 +
1.272 +@leave KErrNoMemory If there is insufficient memory.
1.273 +
1.274 +@see RBuf16::CreateL()
1.275 +*/
1.276 +EXPORT_C LString16::LString16(const TDesC16& aDes)
1.277 + : iReserved(0)
1.278 + {
1.279 + RBuf16::CreateL(aDes);
1.280 + }
1.281 +
1.282 +/**
1.283 +Copies data into this 16-bit string descriptor, replacing any existing
1.284 +data, and expanding its heap buffer to accommodate if necessary.
1.285 +
1.286 +The length of this descriptor is set to reflect the new data.
1.287 +
1.288 +This operation may cause the target string descriptor's heap buffer to
1.289 +be reallocated in order to accommodate the new data. As a result,
1.290 +MaxLength() and Ptr() may return different values afterwards, and any
1.291 +existing raw pointers to into the descriptor data may be invalidated.
1.292 +
1.293 +Note that the automatic resizing performed is a change to the
1.294 +functionality of this operation compared to other descriptor
1.295 +classes. This change is only active on objects directly declared
1.296 +LString16; when LString16 instances are instead manipulated via
1.297 +references to TDes16 or TDesC16, the standard (non-resizing, panicing)
1.298 +variant is invoked.
1.299 +
1.300 +@param aDes A 16-bit non-modifiable descriptor.
1.301 +
1.302 +@return A reference to this 16-bit string descriptor.
1.303 +
1.304 +@leave KErrNoMemory If the heap buffer of the string descriptor being
1.305 + assigned to needs to be expanded, but there is
1.306 + insufficient memory to do so
1.307 +
1.308 +@see LString16::CopyL
1.309 +*/
1.310 +EXPORT_C LString16& LString16::operator=(const TDesC16& aDes)
1.311 + {
1.312 + CopyL(aDes);
1.313 + return *this;
1.314 + }
1.315 +
1.316 +
1.317 +/**
1.318 +Transfers ownership of the specified 16-bit resizable descriptor's this object.
1.319 +
1.320 +@param aBuf The source 16-bit resizable buffer. The ownership of this
1.321 + object's buffer is to be transferred.
1.322 +
1.323 +@return A reference to this 16-bit string descriptor.
1.324 +
1.325 +@see Assign()
1.326 +*/
1.327 +EXPORT_C LString16& LString16::operator=(HBufC16* aBuf)
1.328 + {
1.329 + Assign(aBuf);
1.330 + return *this;
1.331 + }
1.332 +
1.333 +
1.334 +/**
1.335 +Copies data into this 16-bit string descriptor, replacing any existing
1.336 +data, and expanding its heap buffer to accommodate if necessary.
1.337 +
1.338 +The length of this descriptor is set to reflect the new data.
1.339 +
1.340 +This leaving variant of the standard, non-leaving descriptor method
1.341 +differs in that this operation may cause the string descriptor's heap
1.342 +buffer to be reallocated in order to accommodate the new data. As a
1.343 +result, MaxLength() and Ptr() may return different values afterwards,
1.344 +and any existing raw pointers to into the descriptor data may be
1.345 +invalidated.
1.346 +
1.347 +@param aDes A 16-bit non-modifiable descriptor.
1.348 +
1.349 +@leave KErrNoMemory If the heap buffer of the string descriptor being
1.350 + assigned to needs to be expanded, but there is
1.351 + insufficient memory to do so
1.352 +
1.353 +@see LString16::operator=
1.354 +@see TDes16::Copy
1.355 +*/
1.356 +EXPORT_C void LString16::CopyL(const TDesC16& aDes)
1.357 + {
1.358 + ReserveL(aDes.Length());
1.359 + RBuf16::Copy(aDes);
1.360 + }
1.361 +
1.362 +/**
1.363 +Copy constructor to create a 16-bit resizable string descriptor to
1.364 +contain a copy of the specified (source) string descriptor's data, or
1.365 +leave on failure.
1.366 +
1.367 +The constructor allocates sufficient memory so that this string
1.368 +descriptor's maximum length is the same as the length of the source
1.369 +string descriptor. Both the current length and the maximum length of
1.370 +this string descriptor are set to the length of the source descriptor.
1.371 +
1.372 +The data contained in the source string descriptor is copied into this
1.373 +string descriptor.
1.374 +
1.375 +@param aDes Source string descriptor to be copied into this object.
1.376 +
1.377 +@leave KErrNoMemory If there is insufficient memory.
1.378 +
1.379 +@see RBuf16::CreateL()
1.380 +*/
1.381 +EXPORT_C LString16::LString16(const LString16& aDes)
1.382 + : iReserved(0)
1.383 + {
1.384 + RBuf16::CreateL(aDes);
1.385 + }
1.386 +
1.387 +
1.388 +/**
1.389 +Copies data into this 16-bit string descriptor, replacing any existing
1.390 +data, and expanding its heap buffer to accommodate if necessary.
1.391 +
1.392 +The length of this descriptor is set to reflect the new data.
1.393 +
1.394 +This operation may cause the target string descriptor's heap buffer to
1.395 +be reallocated in order to accommodate the new data. As a result,
1.396 +MaxLength() and Ptr() may return different values afterwards, and any
1.397 +existing raw pointers to into the descriptor data may be invalidated.
1.398 +
1.399 +Note that the automatic resizing performed is a change to the
1.400 +functionality of this operation compared to other descriptor
1.401 +classes. This change is only active on objects directly declared
1.402 +LString16; when LString16 instances are instead manipulated via
1.403 +references to TDes16 or TDesC16, the standard (non-resizing, panicing)
1.404 +variant is invoked.
1.405 +
1.406 +@param aDes A 16-bit string descriptor.
1.407 +
1.408 +@return A reference to this 16-bit string descriptor.
1.409 +
1.410 +@leave KErrNoMemory If the heap buffer of the string descriptor being
1.411 + assigned to needs to be expanded, but there is
1.412 + insufficient memory to do so
1.413 +
1.414 +@see LString16::CopyL
1.415 +*/
1.416 +EXPORT_C LString16& LString16::operator=(const LString16& aDes)
1.417 + {
1.418 + CopyL(aDes);
1.419 + return *this;
1.420 + }
1.421 +
1.422 +/**
1.423 +Constructor to create a 16-bit resizable string descriptor containing
1.424 +a copy of the specified (source) zero-terminated string data, or leave
1.425 +on failure.
1.426 +
1.427 +The constructor allocates sufficient memory so that this string
1.428 +descriptor's maximum length is the same as the length of the source
1.429 +string. Both the current length and the maximum length of this string
1.430 +descriptor are set to the length of the source string.
1.431 +
1.432 +The data contained in the source string is copied into this string
1.433 +descriptor. The zero terminator is not copied.
1.434 +
1.435 +@param aZeroTerminatedString A pointer to a zero-terminated string
1.436 +
1.437 +@leave KErrNoMemory If there is insufficient memory.
1.438 +
1.439 +@see LString16::CopyL
1.440 +*/
1.441 +EXPORT_C LString16::LString16(const TUint16* aZeroTerminatedString)
1.442 + : iReserved(0)
1.443 + {
1.444 + CopyL(aZeroTerminatedString);
1.445 + }
1.446 +
1.447 +/**
1.448 +Copies data into this 16-bit string descriptor, replacing any existing
1.449 +data, and expanding its heap buffer to accommodate if necessary.
1.450 +
1.451 +The length of this descriptor is set to reflect the new data.
1.452 +
1.453 +This operation may cause the target string descriptor's heap buffer to
1.454 +be reallocated in order to accommodate the new data. As a result,
1.455 +MaxLength() and Ptr() may return different values afterwards, and any
1.456 +existing raw pointers to into the descriptor data may be invalidated.
1.457 +
1.458 +Note that the automatic resizing performed is a change to the
1.459 +functionality of this operation compared to other descriptor
1.460 +classes. This change is only active on objects directly declared
1.461 +LString16; when LString16 instances are instead manipulated via
1.462 +references to TDes16 or TDesC16, the standard (non-resizing, panicing)
1.463 +variant is invoked.
1.464 +
1.465 +@param aZeroTerminatedString A pointer to a zero-terminated string
1.466 +
1.467 +@return A reference to this 16-bit string descriptor.
1.468 +
1.469 +@leave KErrNoMemory If the heap buffer of the string descriptor being
1.470 + assigned to needs to be expanded, but there is
1.471 + insufficient memory to do so
1.472 +
1.473 +@see LString16::CopyL
1.474 +*/
1.475 +EXPORT_C LString16& LString16::operator=(const TUint16* aZeroTerminatedString)
1.476 + {
1.477 + CopyL(aZeroTerminatedString);
1.478 + return *this;
1.479 + }
1.480 +
1.481 +/**
1.482 +Copies data into this 16-bit string descriptor, replacing any existing
1.483 +data, and expanding its heap buffer to accommodate if necessary.
1.484 +
1.485 +The length of this descriptor is set to reflect the new data.
1.486 +
1.487 +This leaving variant of the standard, non-leaving descriptor method
1.488 +differs in that this operation may cause the string descriptor's heap
1.489 +buffer to be reallocated in order to accommodate the new data. As a
1.490 +result, MaxLength() and Ptr() may return different values afterwards,
1.491 +and any existing raw pointers to into the descriptor data may be
1.492 +invalidated.
1.493 +
1.494 +@param aZeroTerminatedString A pointer to a zero-terminated string
1.495 +
1.496 +@leave KErrNoMemory If the heap buffer of the string descriptor being
1.497 + assigned to needs to be expanded, but there is
1.498 + insufficient memory to do so
1.499 +
1.500 +@see LString16::operator=
1.501 +@see TDes16::Copy
1.502 +*/
1.503 +EXPORT_C void LString16::CopyL(const TUint16* aZeroTerminatedString)
1.504 + {
1.505 + ReserveL(User::StringLength(aZeroTerminatedString));
1.506 + RBuf16::Copy(aZeroTerminatedString);
1.507 + }
1.508 +
1.509 +/**
1.510 +Copies 8-bit descriptor data into this 16-bit string descriptor,
1.511 +replacing any existing data, and expanding its heap buffer to
1.512 +accommodate if necessary.
1.513 +
1.514 +The length of this descriptor is set to reflect the new data.
1.515 +
1.516 +Each 8-bit character value is widened to a 16-bit character value as
1.517 +part of the copying process.
1.518 +
1.519 +This leaving variant of the standard, non-leaving descriptor method
1.520 +differs in that this operation may cause the string descriptor's heap
1.521 +buffer to be reallocated in order to accommodate the new data. As a
1.522 +result, MaxLength() and Ptr() may return different values afterwards,
1.523 +and any existing raw pointers to into the descriptor data may be
1.524 +invalidated.
1.525 +
1.526 +@param aDes An 8 bit non modifiable descriptor.
1.527 +
1.528 +@leave KErrNoMemory If the heap buffer of the string descriptor being
1.529 + assigned to needs to be expanded, but there is
1.530 + insufficient memory to do so
1.531 +
1.532 +@see LString16::operator=
1.533 +@see TDes16::Copy
1.534 +*/
1.535 +EXPORT_C void LString16::CopyL(const TDesC8& aDes)
1.536 + {
1.537 + ReserveL(aDes.Length());
1.538 + RBuf16::Copy(aDes);
1.539 + }
1.540 +
1.541 +/**
1.542 +Copies data into this 16-bit string descriptor, replacing any existing
1.543 +data, and expanding its heap buffer to accommodate if necessary.
1.544 +
1.545 +The length of this descriptor is set according to the second
1.546 +parameter.
1.547 +
1.548 +This leaving variant of the standard, non-leaving descriptor method
1.549 +differs in that this operation may cause the string descriptor's heap
1.550 +buffer to be reallocated in order to accommodate the new data. As a
1.551 +result, MaxLength() and Ptr() may return different values afterwards,
1.552 +and any existing raw pointers to into the descriptor data may be
1.553 +invalidated.
1.554 +
1.555 +@param aBuf The start address of data to be copied.
1.556 +@param aLength The length of data to be copied.
1.557 +
1.558 +@leave KErrNoMemory If the heap buffer of the string descriptor being
1.559 + assigned to needs to be expanded, but there is
1.560 + insufficient memory to do so
1.561 +
1.562 +@panic USER 11 if aLength is negative.
1.563 +
1.564 +@see TDes16::Copy
1.565 +*/
1.566 +EXPORT_C void LString16::CopyL(const TUint16* aBuf,TInt aLength)
1.567 + {
1.568 + ReserveL(aLength);
1.569 + RBuf16::Copy(aBuf, aLength);
1.570 + }
1.571 +
1.572 +
1.573 +/**
1.574 +Sets the length of the data represented by the string descriptor to
1.575 +the specified value.
1.576 +
1.577 +This leaving variant of the standard, non-leaving descriptor method
1.578 +differs in that this operation may cause the string descriptor's heap
1.579 +buffer to be reallocated in order to accommodate the new data. As a
1.580 +result, MaxLength() and Ptr() may return different values afterwards,
1.581 +and any existing raw pointers to into the descriptor data may be
1.582 +invalidated.
1.583 +
1.584 +@param aLength The new length of the descriptor.
1.585 +
1.586 +@leave KErrNoMemory if the underlying buffer needs to be
1.587 +grown and there are insufficient resources to do so
1.588 +
1.589 +@panic USER 11 if aLength is negative
1.590 +*/
1.591 +EXPORT_C void LString16::SetLengthL(TInt aLength)
1.592 + {
1.593 + ReserveL(aLength);
1.594 + RBuf16::SetLength(aLength);
1.595 + }
1.596 +
1.597 +
1.598 +/**
1.599 +Sets the storage space allocated to this descriptor to the specified
1.600 +value by growing or compressing its buffer size.
1.601 +
1.602 +If the current length of the descriptor is greater than the specified
1.603 +max length, length is truncated to max length.
1.604 +
1.605 +This leaving variant of the standard, non-leaving descriptor method
1.606 +differs in that this operation may cause the string descriptor's heap
1.607 +buffer to be reallocated in order to accommodate the new data. As a
1.608 +result, MaxLength() and Ptr() may return different values afterwards,
1.609 +and any existing raw pointers to into the descriptor data may be
1.610 +invalidated.
1.611 +
1.612 +@param aMaxLength The new maximum length of the descriptor.
1.613 +
1.614 +@leave KErrNoMemory if the the buffer needs to be
1.615 +reallocated and there are insufficient resources to do so
1.616 +
1.617 +@panic USER 11 if aLength is negative
1.618 +*/
1.619 +EXPORT_C void LString16::SetMaxLengthL(TInt aMaxLength)
1.620 + {
1.621 + if (MaxLength() == aMaxLength)
1.622 + {
1.623 + return;
1.624 + }
1.625 +
1.626 + if (Length() > aMaxLength)
1.627 + {
1.628 + // truncate the current length
1.629 + RBuf16::SetLength(aMaxLength);
1.630 + }
1.631 +
1.632 + ReAllocL(aMaxLength);
1.633 + }
1.634 +
1.635 +
1.636 +/**
1.637 +Ensures that the remaining unused space is more than the supplied value.
1.638 +
1.639 +May reallocate a larger storage space to meet the requirement.
1.640 +As a result MaxLength() and Ptr() may return different values afterwards,
1.641 +and any existing raw pointers to into the descriptor data may be
1.642 +invalidated.
1.643 +
1.644 +Typically, you use this method to reserve a known amount of required space
1.645 +in one go instead of relying on the automatic growth pattern.
1.646 +
1.647 +@param aExtraSpaceLength The extra space required.
1.648 +
1.649 +@leave KErrNoMemory if the the buffer needs to be
1.650 +reallocated and there are insufficient resources to do so.
1.651 +
1.652 +@panic USER 11 if aLength is negative
1.653 +*/
1.654 +EXPORT_C void LString16::ReserveFreeCapacityL(TInt aExtraSpaceLength)
1.655 + {
1.656 + ReserveL(Length() + aExtraSpaceLength);
1.657 + }
1.658 +
1.659 +
1.660 +/**
1.661 +Re-initialises the descriptor destroying its payload
1.662 +
1.663 +*/
1.664 +EXPORT_C void LString16::Reset()
1.665 + {
1.666 + RBuf16::Close();
1.667 + }
1.668 +
1.669 +
1.670 +/**
1.671 +Re-allocates a smaller descriptor buffer space to the current
1.672 +descriptor length
1.673 +
1.674 +This may cause the string descriptor's heap buffer to be reallocated
1.675 +in order to accommodate the new data. As a
1.676 +result, MaxLength() and Ptr() may return different values afterwards,
1.677 +and any existing raw pointers to into the descriptor data may be
1.678 +invalidated.
1.679 +
1.680 +If there is insufficient memory to re-allocate the buffer then the
1.681 +descriptor left unchanged
1.682 +*/
1.683 +EXPORT_C void LString16::Compress()
1.684 + {
1.685 + TInt length = Length();
1.686 + if (MaxLength() > length)
1.687 + {
1.688 + ReAlloc(length);
1.689 + }
1.690 + }
1.691 +
1.692 +
1.693 +/**
1.694 +Appends data onto the end of this descriptor's data.
1.695 +
1.696 +The length of this descriptor is incremented to reflect the new content.
1.697 +
1.698 +This leaving variant of the standard, non-leaving descriptor method
1.699 +differs in that this operation may cause the string descriptor's heap
1.700 +buffer to be reallocated in order to accommodate the new data. As a
1.701 +result, MaxLength() and Ptr() may return different values afterwards,
1.702 +and any existing raw pointers to into the descriptor data may be
1.703 +invalidated.
1.704 +
1.705 +@param aChar A single character to be appended. The length of the descriptor
1.706 + is incremented by one.
1.707 +
1.708 +@leave KErrNoMemory if the underlying buffer needs to be
1.709 +grown and there are insufficient resources to do so
1.710 +
1.711 +@see LString16::operator+=
1.712 +*/
1.713 +EXPORT_C void LString16::AppendL(TChar aChar)
1.714 + {
1.715 + ReserveFreeCapacityGrowExponentialL(1);
1.716 + RBuf16::Append(aChar);
1.717 + }
1.718 +
1.719 +/**
1.720 +Appends data onto the end of this descriptor's data.
1.721 +
1.722 +The length of this descriptor is incremented to reflect the new content.
1.723 +
1.724 +This leaving variant of the standard, non-leaving descriptor method
1.725 +differs in that this operation may cause the string descriptor's heap
1.726 +buffer to be reallocated in order to accommodate the new data. As a
1.727 +result, MaxLength() and Ptr() may return different values afterwards,
1.728 +and any existing raw pointers to into the descriptor data may be
1.729 +invalidated.
1.730 +
1.731 +@param aChar A single character to be appended. The length of the descriptor
1.732 + is incremented by one.
1.733 +
1.734 +@leave KErrNoMemory if the underlying buffer needs to be
1.735 +grown and there are insufficient resources to do so
1.736 +
1.737 +@see LString16::AppendL
1.738 +*/
1.739 +EXPORT_C LString16& LString16::operator+=(TChar aChar)
1.740 + {
1.741 + AppendL(aChar);
1.742 + return *this;
1.743 + }
1.744 +
1.745 +/**
1.746 +Appends data onto the end of this descriptor's data.
1.747 +
1.748 +The length of this descriptor is incremented to reflect the new content.
1.749 +
1.750 +This leaving variant of the standard, non-leaving descriptor method
1.751 +differs in that this operation may cause the string descriptor's heap
1.752 +buffer to be reallocated in order to accommodate the new data. As a
1.753 +result, MaxLength() and Ptr() may return different values afterwards,
1.754 +and any existing raw pointers to into the descriptor data may be
1.755 +invalidated.
1.756 +
1.757 +@param aDes A 16-bit non modifiable descriptor whose data is to be appended.
1.758 +
1.759 +@leave KErrNoMemory if the underlying buffer needs to be
1.760 +grown and there are insufficient resources to do so
1.761 +*/
1.762 +EXPORT_C void LString16::AppendL(const TDesC16& aDes)
1.763 + {
1.764 + ReserveFreeCapacityGrowExponentialL(aDes.Length());
1.765 + RBuf16::Append(aDes);
1.766 + }
1.767 +
1.768 +/**
1.769 +Appends data onto the end of this descriptor's data.
1.770 +
1.771 +The length of this descriptor is incremented to reflect the new content.
1.772 +
1.773 +This leaving variant of the standard, non-leaving descriptor method
1.774 +differs in that this operation may cause the string descriptor's heap
1.775 +buffer to be reallocated in order to accommodate the new data. As a
1.776 +result, MaxLength() and Ptr() may return different values afterwards,
1.777 +and any existing raw pointers to into the descriptor data may be
1.778 +invalidated.
1.779 +
1.780 +@param aDes A 16-bit non modifiable descriptor whose data is to be appended.
1.781 +
1.782 +@leave KErrNoMemory if the underlying buffer needs to be
1.783 +grown and there are insufficient resources to do so
1.784 +
1.785 +@see LString16::AppendL
1.786 +*/
1.787 +EXPORT_C LString16& LString16::operator+=(const TDesC16& aDes)
1.788 + {
1.789 + AppendL(aDes);
1.790 + return *this;
1.791 + }
1.792 +
1.793 +/**
1.794 +Appends data onto the end of this descriptor's data.
1.795 +
1.796 +The length of this descriptor is incremented to reflect the new content.
1.797 +
1.798 +This leaving variant of the standard, non-leaving descriptor method
1.799 +differs in that this operation may cause the string descriptor's heap
1.800 +buffer to be reallocated in order to accommodate the new data. As a
1.801 +result, MaxLength() and Ptr() may return different values afterwards,
1.802 +and any existing raw pointers to into the descriptor data may be
1.803 +invalidated.
1.804 +
1.805 +@param aBuf A pointer to the data to be copied.
1.806 +@param aLength The length of data to be copied.
1.807 +
1.808 +@leave KErrNoMemory if the underlying buffer needs to be
1.809 +grown and there are insufficient resources to do so
1.810 +
1.811 +@panic USER 17 if aLength is negative.
1.812 +*/
1.813 +EXPORT_C void LString16::AppendL(const TUint16* aBuf,TInt aLength)
1.814 + {
1.815 + ReserveFreeCapacityGrowExponentialL(aLength);
1.816 + RBuf16::Append(aBuf, aLength);
1.817 + }
1.818 +
1.819 +/**
1.820 +Fills the descriptor's data area with the specified character, replacing any
1.821 +existing data.
1.822 +
1.823 +The descriptor is filled with the specified number of characters,
1.824 +and its length is changed to reflect this.
1.825 +
1.826 +This leaving variant of the standard, non-leaving descriptor method
1.827 +differs in that this operation may cause the string descriptor's heap
1.828 +buffer to be reallocated in order to accommodate the new data. As a
1.829 +result, MaxLength() and Ptr() may return different values afterwards,
1.830 +and any existing raw pointers to into the descriptor data may be
1.831 +invalidated.
1.832 +
1.833 +@param aChar The fill character.
1.834 +@param aLength The new length of the descriptor and the number of fill characters
1.835 + to be copied into it.
1.836 +
1.837 +@leave KErrNoMemory if the underlying buffer needs to be
1.838 +grown and there are insufficient resources to do so
1.839 +
1.840 +@panic USER 11 if aLength is negative
1.841 +*/
1.842 +EXPORT_C void LString16::FillL(TChar aChar,TInt aLength)
1.843 + {
1.844 + ReserveL(aLength);
1.845 + RBuf16::Fill(aChar, aLength);
1.846 + }
1.847 +
1.848 +/**
1.849 +Fills the descriptor's data area with binary zeroes, i.e. 0x0000, replacing any
1.850 +existing data, and changes its length.
1.851 +
1.852 +The descriptor is filled with the specified number of binary zeroes.
1.853 +The descriptor's length is changed to reflect this.
1.854 +
1.855 +This leaving variant of the standard, non-leaving descriptor method
1.856 +differs in that this operation may cause the string descriptor's heap
1.857 +buffer to be reallocated in order to accommodate the new data. As a
1.858 +result, MaxLength() and Ptr() may return different values afterwards,
1.859 +and any existing raw pointers to into the descriptor data may be
1.860 +invalidated.
1.861 +
1.862 +@param aLength The new length of the descriptor and the number of binary zeroes
1.863 + to be copied into it.
1.864 +
1.865 +@leave KErrNoMemory if the underlying buffer needs to be
1.866 +grown and there are insufficient resources to do so
1.867 +
1.868 +@panic USER 11 if aLength is negative
1.869 +*/
1.870 +EXPORT_C void LString16::FillZL(TInt aLength)
1.871 + {
1.872 + ReserveL(aLength);
1.873 + RBuf16::FillZ(aLength);
1.874 + }
1.875 +
1.876 +/**
1.877 +Converts the specified unsigned integer into a fixed width character
1.878 +representation based on the specified number system and copies the conversion
1.879 +into this descriptor, replacing any existing data.
1.880 +
1.881 +The length of this descriptor is set to reflect the new data.
1.882 +
1.883 +The function generates the exact number of specified characters, either padding
1.884 +to the left with character zeroes or discarding low order characters as necessary.
1.885 +
1.886 +When a hexadecimal conversion is specified, hexadecimal characters are in
1.887 +lower case.
1.888 +
1.889 +This function is equivalent to using Format() with parameters which specify:
1.890 +
1.891 +1. a fixed length target field
1.892 +
1.893 +2. padding with zero characters, for example "%08x".
1.894 +
1.895 +When this is the case, always use NumFixedWidth() in preference
1.896 +to Format() as it is more efficient.
1.897 +
1.898 +This leaving variant of the standard, non-leaving descriptor method
1.899 +differs in that this operation may cause the string descriptor's heap
1.900 +buffer to be reallocated in order to accommodate the new data. As a
1.901 +result, MaxLength() and Ptr() may return different values afterwards,
1.902 +and any existing raw pointers to into the descriptor data may be
1.903 +invalidated.
1.904 +
1.905 +@param aVal The unsigned integer value.
1.906 +@param aRadix The number system representation for the unsigned integer.
1.907 +@param aWidth The number of characters: to be used to contain the conversion,
1.908 + to be copied into this descriptor.
1.909 +
1.910 +@leave KErrNoMemory if the underlying buffer needs to be
1.911 +grown and there are insufficient resources to do so
1.912 +*/
1.913 +EXPORT_C void LString16::NumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth)
1.914 + {
1.915 + Zero();
1.916 + AppendNumFixedWidthL(aVal, aRadix, aWidth);
1.917 + }
1.918 +
1.919 +/**
1.920 +Converts the specified unsigned integer into a fixed width character
1.921 +representation based on the specified number system and appends the conversion
1.922 +onto the end of this descriptor's data.
1.923 +
1.924 +The length of this descriptor is incremented to reflect the new content.
1.925 +
1.926 +The function generates the exact number of specified characters, either padding
1.927 +to the left with character zeroes or discarding low order characters as
1.928 +necessary.
1.929 +
1.930 +When a hexadecimal conversion is specified, hexadecimal characters are in
1.931 +lower case.
1.932 +
1.933 +This leaving variant of the standard, non-leaving descriptor method
1.934 +differs in that this operation may cause the string descriptor's heap
1.935 +buffer to be reallocated in order to accommodate the new data. As a
1.936 +result, MaxLength() and Ptr() may return different values afterwards,
1.937 +and any existing raw pointers to into the descriptor data may be
1.938 +invalidated.
1.939 +
1.940 +@param aVal The unsigned integer value.
1.941 +@param aRadix The number system representation for the unsigned integer.
1.942 +@param aWidth The number of characters to be used to contain the conversion,
1.943 + and to be appended to this descriptor.
1.944 +
1.945 +@leave KErrNoMemory if the underlying buffer needs to be
1.946 +grown and there are insufficient resources to do so
1.947 +*/
1.948 +EXPORT_C void LString16::AppendNumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth)
1.949 + {
1.950 + ReserveFreeCapacityGrowExponentialL(aWidth);
1.951 + RBuf16::AppendNumFixedWidth(aVal, aRadix, aWidth);
1.952 + }
1.953 +
1.954 +/**
1.955 +Appends a zero terminator onto the end of this descriptor's data and returns
1.956 +a pointer to the data.
1.957 +
1.958 +The length of the descriptor is not changed, but the capacity of the
1.959 +descriptor may need to be grown to accommodate the zero terminator.
1.960 +
1.961 +This leaving variant of the standard, non-leaving descriptor method
1.962 +differs in that this operation may cause the string descriptor's heap
1.963 +buffer to be reallocated in order to accommodate the new data. As a
1.964 +result, MaxLength() and Ptr() may return different values afterwards,
1.965 +and any existing raw pointers to into the descriptor data may be
1.966 +invalidated.
1.967 +
1.968 +@return A pointer to the descriptor's zero terminated data.
1.969 +
1.970 +@leave KErrNoMemory if the underlying buffer needs to be
1.971 +grown and there are insufficient resources to do so
1.972 +*/
1.973 +EXPORT_C const TUint16 *LString16::PtrZL()
1.974 + {
1.975 + ReserveFreeCapacityL(1);
1.976 + return RBuf16::PtrZ();
1.977 + }
1.978 +
1.979 +/**
1.980 +Copies and folds data from the specified descriptor into this descriptor replacing
1.981 +any existing data.
1.982 +
1.983 +The length of this descriptor is set to reflect the new
1.984 +data.
1.985 +
1.986 +Note that folding is locale-independent behaviour. It is also important to
1.987 +note that there can be no guarantee that folding is in any way culturally
1.988 +appropriate, and should not be used when dealing with strings in natural
1.989 +language.
1.990 +
1.991 +This leaving variant of the standard, non-leaving descriptor method
1.992 +differs in that this operation may cause the string descriptor's heap
1.993 +buffer to be reallocated in order to accommodate the new data. As a
1.994 +result, MaxLength() and Ptr() may return different values afterwards,
1.995 +and any existing raw pointers to into the descriptor data may be
1.996 +invalidated.
1.997 +
1.998 +@param aDes A 16-bit non-modifiable descriptor.
1.999 +
1.1000 +@leave KErrNoMemory if the underlying buffer needs to be
1.1001 +grown and there are insufficient resources to do so
1.1002 +*/
1.1003 +EXPORT_C void LString16::CopyFL(const TDesC16& aDes)
1.1004 + {
1.1005 + ReserveL(aDes.Length());
1.1006 + RBuf16::CopyF(aDes);
1.1007 + }
1.1008 +
1.1009 +/**
1.1010 +Copies and collates data from the specified descriptor
1.1011 +into this descriptor replacing any existing data.
1.1012 +
1.1013 +The length of this descriptor is set to reflect the new data.
1.1014 +
1.1015 +This leaving variant of the standard, non-leaving descriptor method
1.1016 +differs in that this operation may cause the string descriptor's heap
1.1017 +buffer to be reallocated in order to accommodate the new data. As a
1.1018 +result, MaxLength() and Ptr() may return different values afterwards,
1.1019 +and any existing raw pointers to into the descriptor data may be
1.1020 +invalidated.
1.1021 +
1.1022 +@param aDes A 16-bit non-modifiable descriptor.
1.1023 +
1.1024 +@leave KErrNoMemory if the underlying buffer needs to be
1.1025 +grown and there are insufficient resources to do so
1.1026 +*/
1.1027 +EXPORT_C void LString16::CopyCL(const TDesC16& aDes)
1.1028 + {
1.1029 + ReserveL(aDes.Length());
1.1030 + RBuf16::CopyC(aDes);
1.1031 + }
1.1032 +
1.1033 +/**
1.1034 +Copies text from the specified descriptor and converts it to lower case before
1.1035 +putting it into this descriptor, replacing any existing data.
1.1036 +
1.1037 +The length of this descriptor is set to reflect the new data.
1.1038 +
1.1039 +Conversion to lower case is implemented as appropriate to the current locale.
1.1040 +
1.1041 +This leaving variant of the standard, non-leaving descriptor method
1.1042 +differs in that this operation may cause the string descriptor's heap
1.1043 +buffer to be reallocated in order to accommodate the new data. As a
1.1044 +result, MaxLength() and Ptr() may return different values afterwards,
1.1045 +and any existing raw pointers to into the descriptor data may be
1.1046 +invalidated.
1.1047 +
1.1048 +@param aDes A 16-bit non modifiable descriptor.
1.1049 +
1.1050 +@leave KErrNoMemory if the underlying buffer needs to be
1.1051 +grown and there are insufficient resources to do so
1.1052 +*/
1.1053 +EXPORT_C void LString16::CopyLCL(const TDesC16& aDes)
1.1054 + {
1.1055 + ReserveL(aDes.Length());
1.1056 + RBuf16::CopyLC(aDes);
1.1057 + }
1.1058 +
1.1059 +/**
1.1060 +Copies text from the specified descriptor and converts it to upper case before
1.1061 +putting it into this descriptor, replacing any existing data.
1.1062 +
1.1063 +The length of this descriptor is set to reflect the new data.
1.1064 +
1.1065 +Conversion to upper case is implemented as appropriate to the current locale.
1.1066 +
1.1067 +This leaving variant of the standard, non-leaving descriptor method
1.1068 +differs in that this operation may cause the string descriptor's heap
1.1069 +buffer to be reallocated in order to accommodate the new data. As a
1.1070 +result, MaxLength() and Ptr() may return different values afterwards,
1.1071 +and any existing raw pointers to into the descriptor data may be
1.1072 +invalidated.
1.1073 +
1.1074 +@param aDes A 16-bit non modifiable descriptor.
1.1075 +
1.1076 +@leave KErrNoMemory if the underlying buffer needs to be
1.1077 +grown and there are insufficient resources to do so
1.1078 +*/
1.1079 +EXPORT_C void LString16::CopyUCL(const TDesC16& aDes)
1.1080 + {
1.1081 + ReserveL(aDes.Length());
1.1082 + RBuf16::CopyUC(aDes);
1.1083 + }
1.1084 +
1.1085 +/**
1.1086 +Copies text from the specified descriptor and capitalises it before putting
1.1087 +it into this descriptor, replacing any existing data.
1.1088 +
1.1089 +The length of this descriptor is set to reflect the new data.
1.1090 +
1.1091 +Capitalisation is implemented as appropriate to the current locale.
1.1092 +
1.1093 +This leaving variant of the standard, non-leaving descriptor method
1.1094 +differs in that this operation may cause the string descriptor's heap
1.1095 +buffer to be reallocated in order to accommodate the new data. As a
1.1096 +result, MaxLength() and Ptr() may return different values afterwards,
1.1097 +and any existing raw pointers to into the descriptor data may be
1.1098 +invalidated.
1.1099 +
1.1100 +@param aDes A 16-bit non-modifiable descriptor.
1.1101 +
1.1102 +@leave KErrNoMemory if the underlying buffer needs to be
1.1103 +grown and there are insufficient resources to do so
1.1104 +*/
1.1105 +EXPORT_C void LString16::CopyCPL(const TDesC16& aDes)
1.1106 + {
1.1107 + ReserveL(aDes.Length());
1.1108 + RBuf16::CopyCP(aDes);
1.1109 + }
1.1110 +
1.1111 +/**
1.1112 +Appends and fills this descriptor with the specified character.
1.1113 +
1.1114 +The descriptor is appended with the specified number of characters.
1.1115 +and its length is changed to reflect this.
1.1116 +
1.1117 +This leaving variant of the standard, non-leaving descriptor method
1.1118 +differs in that this operation may cause the string descriptor's heap
1.1119 +buffer to be reallocated in order to accommodate the new data. As a
1.1120 +result, MaxLength() and Ptr() may return different values afterwards,
1.1121 +and any existing raw pointers to into the descriptor data may be
1.1122 +invalidated.
1.1123 +
1.1124 +@param aChar The fill character.
1.1125 +@param aLength The number of fill characters to be appended.
1.1126 +
1.1127 +@leave KErrNoMemory if the underlying buffer needs to be
1.1128 +grown and there are insufficient resources to do so
1.1129 +
1.1130 +@panic USER 11 if aLength is negative
1.1131 +*/
1.1132 +EXPORT_C void LString16::AppendFillL(TChar aChar,TInt aLength)
1.1133 + {
1.1134 + ReserveFreeCapacityGrowExponentialL(aLength);
1.1135 + RBuf16::AppendFill(aChar, aLength);
1.1136 + }
1.1137 +
1.1138 +/**
1.1139 +Appends a zero terminator onto the end of this descriptor's data.
1.1140 +
1.1141 +The length of the descriptor is not changed, but the capacity of the
1.1142 +descriptor may need to be grown to accommodate the zero terminator.
1.1143 +
1.1144 +This leaving variant of the standard, non-leaving descriptor method
1.1145 +differs in that this operation may cause the string descriptor's heap
1.1146 +buffer to be reallocated in order to accommodate the new data. As a
1.1147 +result, MaxLength() and Ptr() may return different values afterwards,
1.1148 +and any existing raw pointers to into the descriptor data may be
1.1149 +invalidated.
1.1150 +
1.1151 +@leave KErrNoMemory if the underlying buffer needs to be
1.1152 +grown and there are insufficient resources to do so
1.1153 +*/
1.1154 +EXPORT_C void LString16::ZeroTerminateL()
1.1155 + {
1.1156 + ReserveFreeCapacityL(1);
1.1157 + RBuf16::ZeroTerminate();
1.1158 + }
1.1159 +
1.1160 +/**
1.1161 +Swaps the data represented by this descriptor with the data represented by
1.1162 +the specified descriptor.
1.1163 +
1.1164 +The lengths of both descriptors are also swapped to reflect the change.
1.1165 +
1.1166 +Note that each descriptor must be capable of accommodating the contents of
1.1167 +the other descriptor.
1.1168 +
1.1169 +Each descriptor must be capable of accommodating the contents of the
1.1170 +other descriptor. If the maximum length of the descriptor parameter is
1.1171 +smaller than the length of the target LString16, then the function
1.1172 +raises a USER 11 panic. The target LString16 will be grown if
1.1173 +necessary to accommodate the descriptor parameter's data.
1.1174 +
1.1175 +This leaving variant of the standard, non-leaving descriptor method
1.1176 +differs in that this operation may cause the string descriptor's heap
1.1177 +buffer to be reallocated in order to accommodate the new data. As a
1.1178 +result, MaxLength() and Ptr() may return different values afterwards,
1.1179 +and any existing raw pointers to into the descriptor data may be
1.1180 +invalidated.
1.1181 +
1.1182 +@param aDes The 16-bit modifiable descriptor whose data is to be swapped with
1.1183 + the data of this descriptor.
1.1184 +
1.1185 +@leave KErrNoMemory if the underlying buffer needs to be
1.1186 +grown and there are insufficient resources to do so
1.1187 +
1.1188 +@panic USER 11 if the maximum length of the descriptor parameter is smaller than the
1.1189 + length of the target LString16
1.1190 +*/
1.1191 +EXPORT_C void LString16::SwapL(TDes16& aDes)
1.1192 + {
1.1193 + ReserveL(aDes.Length());
1.1194 + TDes16::Swap(aDes);
1.1195 + }
1.1196 +
1.1197 +/**
1.1198 +Swaps the data represented by this string descriptor with the data
1.1199 +represented by the specified string descriptor.
1.1200 +
1.1201 +The lengths of both string descriptors are also swapped to reflect the
1.1202 +change, and their buffers grown as necessary to accommodate the data
1.1203 +they receive.
1.1204 +
1.1205 +This leaving variant of the standard, non-leaving descriptor method
1.1206 +differs in that this operation may cause the string descriptor's heap
1.1207 +buffer to be reallocated in order to accommodate the new data. As a
1.1208 +result, MaxLength() and Ptr() may return different values afterwards,
1.1209 +and any existing raw pointers to into the descriptor data may be
1.1210 +invalidated.
1.1211 +
1.1212 +@param aDes The 16-bit modifiable string descriptor whose data is to be swapped with
1.1213 + the data of this descriptor.
1.1214 +
1.1215 +@leave KErrNoMemory if one of the underlying buffers needs to be
1.1216 +grown and there are insufficient resources to do so
1.1217 +*/
1.1218 +EXPORT_C void LString16::SwapL(LString16& aDes)
1.1219 + {
1.1220 + this->ReserveL(aDes.Length());
1.1221 + aDes.ReserveL(this->Length());
1.1222 + TDes16::Swap(aDes);
1.1223 + }
1.1224 +
1.1225 +
1.1226 +/**
1.1227 +Inserts data into this descriptor.
1.1228 +
1.1229 +The length of this descriptor is changed to reflect the extra data.
1.1230 +
1.1231 +This leaving variant of the standard, non-leaving descriptor method
1.1232 +differs in that this operation may cause the string descriptor's heap
1.1233 +buffer to be reallocated in order to accommodate the new data. As a
1.1234 +result, MaxLength() and Ptr() may return different values afterwards,
1.1235 +and any existing raw pointers to into the descriptor data may be
1.1236 +invalidated.
1.1237 +
1.1238 +@param aPos The position within the data where insertion is to start. This
1.1239 + is an offset value; a zero value refers to the leftmost data
1.1240 + position.
1.1241 +
1.1242 +@param aDes A 16-bit non modifiable descriptor whose data is to be inserted.
1.1243 +
1.1244 +@leave KErrNoMemory if the underlying buffer needs to be
1.1245 +grown and there are insufficient resources to do so
1.1246 +
1.1247 +@panic USER 10 if aPos is negative or is greater than the length of this
1.1248 + descriptor.
1.1249 +*/
1.1250 +EXPORT_C void LString16::InsertL(TInt aPos,const TDesC16& aDes)
1.1251 + {
1.1252 + ReserveFreeCapacityGrowExponentialL(aDes.Length());
1.1253 + RBuf16::Insert(aPos, aDes);
1.1254 + }
1.1255 +
1.1256 +/**
1.1257 +Replaces data in this descriptor.
1.1258 +
1.1259 +The specified length can be different to the length of the replacement data.
1.1260 +The length of this descriptor changes to reflect the change of data.
1.1261 +
1.1262 +This leaving variant of the standard, non-leaving descriptor method
1.1263 +differs in that this operation may cause the string descriptor's heap
1.1264 +buffer to be reallocated in order to accommodate the new data. As a
1.1265 +result, MaxLength() and Ptr() may return different values afterwards,
1.1266 +and any existing raw pointers to into the descriptor data may be
1.1267 +invalidated.
1.1268 +
1.1269 +@param aPos The position within the data where replacement is to start.
1.1270 + This is an offset value; a zero value refers to the leftmost
1.1271 + data position.
1.1272 +
1.1273 +@param aLength The length of data to be replaced.
1.1274 +
1.1275 +@param aDes The source 16-bit non modifiable descriptor whose data is to
1.1276 + replace the target descriptor's data at aPos.
1.1277 +
1.1278 +@leave KErrNoMemory if the underlying buffer needs to be
1.1279 +grown and there are insufficient resources to do so
1.1280 +
1.1281 +@panic USER 8 if aLength is negative
1.1282 +
1.1283 +@panic USER 10 if aPos is negative or is greater than the length of this
1.1284 + descriptor.
1.1285 +
1.1286 +@panic USER 16 if the length of the source descriptor aDes is negative
1.1287 +*/
1.1288 +EXPORT_C void LString16::ReplaceL(TInt aPos,TInt aLength,const TDesC16& aDes)
1.1289 + {
1.1290 + TInt delta = aDes.Length() - aLength;
1.1291 + if (delta > 0)
1.1292 + {
1.1293 + ReserveFreeCapacityGrowExponentialL(delta);
1.1294 + }
1.1295 + RBuf16::Replace(aPos, aLength, aDes);
1.1296 + }
1.1297 +
1.1298 +/**
1.1299 +Copies data into this descriptor and justifies it, replacing any existing data.
1.1300 +
1.1301 +The length of this descriptor is set to reflect the new data.
1.1302 +
1.1303 +The target area is considered to be an area of specified width positioned at
1.1304 +the beginning of this descriptor's data area. Source data is copied into, and
1.1305 +aligned within this target area according to the specified alignment
1.1306 +instruction.
1.1307 +
1.1308 +If the length of the target area is larger than the length of the source, then
1.1309 +spare space within the target area is padded with the fill character.
1.1310 +
1.1311 +This leaving variant of the standard, non-leaving descriptor method
1.1312 +differs in that this operation may cause the string descriptor's heap
1.1313 +buffer to be reallocated in order to accommodate the new data. As a
1.1314 +result, MaxLength() and Ptr() may return different values afterwards,
1.1315 +and any existing raw pointers to into the descriptor data may be
1.1316 +invalidated.
1.1317 +
1.1318 +@param aDes A 16-bit non-modifiable descriptor containing the source data.
1.1319 + The length of the data to be copied is the smaller of:
1.1320 + the length of the source descriptor, and
1.1321 + the width of the target area (only if this is not the
1.1322 + explicit negative value KDefaultJustifyWidth).
1.1323 +
1.1324 +@param aWidth The width of the target area. If this has the specific
1.1325 + negative value KDefaultJustifyWidth, then the width is
1.1326 + re-set to the length of the data source.
1.1327 +
1.1328 +@param aAlignment The alignment of the data within the target area
1.1329 +
1.1330 +@param aFill The fill character used to pad the target area.
1.1331 +
1.1332 +@leave KErrNoMemory if the underlying buffer needs to be
1.1333 +grown and there are insufficient resources to do so
1.1334 +
1.1335 +@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
1.1336 +*/
1.1337 +EXPORT_C void LString16::JustifyL(const TDesC16& aDes,TInt aWidth,TAlign aAlignment,TChar aFill)
1.1338 + {
1.1339 + TInt width = (aWidth == KDefaultJustifyWidth ? aDes.Length() : aWidth);
1.1340 + ReserveL(width);
1.1341 + RBuf16::Justify(aDes, aWidth, aAlignment, aFill);
1.1342 + }
1.1343 +
1.1344 +/**
1.1345 +Converts the specified unsigned integer into a fixed width character
1.1346 +representation based on the specified number system and copies the conversion
1.1347 +into this descriptor, replacing any existing data.
1.1348 +
1.1349 +The length of this descriptor is set to reflect the new data.
1.1350 +
1.1351 +The function generates the exact number of specified characters, either padding
1.1352 +to the left with character zeroes or discarding low order characters as
1.1353 +necessary.
1.1354 +
1.1355 +When a hexadecimal conversion is specified, hexadecimal characters are in
1.1356 +upper case.
1.1357 +
1.1358 +This function is equivalent to using Format() with parameters which specify:
1.1359 +
1.1360 +1. a fixed length target field
1.1361 +
1.1362 +2. padding with zero characters, for example "%08x".
1.1363 +
1.1364 +When this is the case, always use NumFixedWidthUC() in
1.1365 +preference to Format() as it is more efficient.
1.1366 +
1.1367 +This leaving variant of the standard, non-leaving descriptor method
1.1368 +differs in that this operation may cause the string descriptor's heap
1.1369 +buffer to be reallocated in order to accommodate the new data. As a
1.1370 +result, MaxLength() and Ptr() may return different values afterwards,
1.1371 +and any existing raw pointers to into the descriptor data may be
1.1372 +invalidated.
1.1373 +
1.1374 +@param aVal The unsigned integer value.
1.1375 +@param aRadix The number system representation for the unsigned integer.
1.1376 +@param aWidth The number of characters: to be used to contain the conversion,
1.1377 + to be copied into this descriptor.
1.1378 +
1.1379 +@leave KErrNoMemory if the underlying buffer needs to be
1.1380 +grown and there are insufficient resources to do so
1.1381 +
1.1382 +@see TDes16::Format()
1.1383 +*/
1.1384 +EXPORT_C void LString16::NumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth)
1.1385 + {
1.1386 + Zero();
1.1387 + AppendNumFixedWidthUCL(aVal, aRadix, aWidth);
1.1388 + }
1.1389 +
1.1390 +/**
1.1391 +Converts the specified 64 bit unsigned integer into a character representation
1.1392 +based on the specified number system and copies the conversion into this
1.1393 +descriptor, replacing any existing data.
1.1394 +
1.1395 +The length of this descriptor is set to reflect the new data.
1.1396 +
1.1397 +When a hexadecimal conversion is specified, hexadecimal characters are in
1.1398 +upper case.
1.1399 +
1.1400 +This leaving variant of the standard, non-leaving descriptor method
1.1401 +differs in that this operation may cause the string descriptor's heap
1.1402 +buffer to be reallocated in order to accommodate the new data. As a
1.1403 +result, MaxLength() and Ptr() may return different values afterwards,
1.1404 +and any existing raw pointers to into the descriptor data may be
1.1405 +invalidated.
1.1406 +
1.1407 +@param aVal The 64 bit integer value. This is always treated as an unsigned
1.1408 + value for all builds.
1.1409 +@param aRadix The number system representation for the 64 bit integer. If no
1.1410 + explicit value is specified, then EDecimal is the default.
1.1411 +
1.1412 +@leave KErrNoMemory if the underlying buffer needs to be
1.1413 +grown and there are insufficient resources to do so
1.1414 +*/
1.1415 +EXPORT_C void LString16::NumUCL(TUint64 aVal, TRadix aRadix)
1.1416 + {
1.1417 + Zero();
1.1418 + AppendNumUCL(aVal, aRadix);
1.1419 + }
1.1420 +
1.1421 +/**
1.1422 +Converts the specified floating point number into a character representation
1.1423 +and copies the conversion into this descriptor, replacing any existing data.
1.1424 +
1.1425 +The length of this descriptor is set to reflect the new data.
1.1426 +
1.1427 +The character representation of the real number is dictated by the specified
1.1428 +format.
1.1429 +
1.1430 +Note that the function leaves if the iType data member of the specified
1.1431 +TRealFormat object has both an invalid character representation format
1.1432 +(i.e. the format type) and invalid format flags.
1.1433 +
1.1434 +This leaving variant of the standard, non-leaving descriptor method
1.1435 +differs in that this operation may cause the string descriptor's heap
1.1436 +buffer to be reallocated in order to accommodate the new data. As a
1.1437 +result, MaxLength() and Ptr() may return different values afterwards,
1.1438 +and any existing raw pointers to into the descriptor data may be
1.1439 +invalidated.
1.1440 +
1.1441 +@param aVal The floating point number to be converted.
1.1442 +@param aFormat The format of the conversion.
1.1443 +
1.1444 +@return If the conversion is successful, the length of this descriptor. If
1.1445 + the conversion fails, a negative value indicating the cause of failure.
1.1446 + In addition, extra information on the cause of the failure may be
1.1447 + appended onto this descriptor. The possible values and their meaning
1.1448 + are:
1.1449 +
1.1450 + 1.KErrArgument - the supplied floating point number is not a valid
1.1451 + number. The three characters NaN are appended to this descriptor.
1.1452 +
1.1453 + 2.KErrOverflow - the number is too large to represent.
1.1454 + 2.1 For positive overflow, the three characters Inf are appended
1.1455 + to this descriptor.
1.1456 + 2.2 For negative overflow, the four characters -Inf are appended
1.1457 + to this descriptor.
1.1458 +
1.1459 + 3.KErrUnderflow - the number is too small to represent.
1.1460 + 3.1 For positive underflow, the three characters Inf are appended
1.1461 + to this descriptor.
1.1462 + 3.2 For negative underflow, the four characters -Inf are appended
1.1463 + to this descriptor.
1.1464 +
1.1465 + 4.KErrGeneral - the conversion cannot be completed. There are a
1.1466 + number of possible reasons for this, but the most common is:
1.1467 + 4.1 The character representation format (i.e. the format type), as
1.1468 + defined in the TRealFormat object is not recognised.
1.1469 +
1.1470 +@leave KErrNoMemory if the underlying buffer needs to be
1.1471 +grown and there are insufficient resources to do so
1.1472 +
1.1473 +@see TRealFormat::iType
1.1474 +*/
1.1475 +EXPORT_C TInt LString16::NumL(TReal aVal,const TRealFormat &aFormat)
1.1476 + {
1.1477 + Zero();
1.1478 + return AppendNumL(aVal, aFormat);
1.1479 + }
1.1480 +
1.1481 +/**
1.1482 +Converts the 64-bit signed integer into a decimal character representation
1.1483 +and copies the conversion into this descriptor, replacing any existing data.
1.1484 +
1.1485 +The length of this descriptor is set to reflect the new data.
1.1486 +
1.1487 +If the integer is negative, the character representation is prefixed by a
1.1488 +minus sign.
1.1489 +
1.1490 +This leaving variant of the standard, non-leaving descriptor method
1.1491 +differs in that this operation may cause the string descriptor's heap
1.1492 +buffer to be reallocated in order to accommodate the new data. As a
1.1493 +result, MaxLength() and Ptr() may return different values afterwards,
1.1494 +and any existing raw pointers to into the descriptor data may be
1.1495 +invalidated.
1.1496 +
1.1497 +@param aVal The 64-bit signed integer value.
1.1498 +
1.1499 +@leave KErrNoMemory if the underlying buffer needs to be
1.1500 +grown and there are insufficient resources to do so
1.1501 +*/
1.1502 +EXPORT_C void LString16::NumL(TInt64 aVal)
1.1503 + {
1.1504 + Zero();
1.1505 + AppendNumL(aVal);
1.1506 + }
1.1507 +
1.1508 +/**
1.1509 +Converts the specified 64 bit unsigned integer into a character representation
1.1510 +based on the specified number system and copies the conversion into this
1.1511 +descriptor, replacing any existing data.
1.1512 +
1.1513 +The length of this descriptor is set to reflect the new data.
1.1514 +
1.1515 +When a hexadecimal conversion is specified, hexadecimal characters are in
1.1516 +lower case.
1.1517 +
1.1518 +This leaving variant of the standard, non-leaving descriptor method
1.1519 +differs in that this operation may cause the string descriptor's heap
1.1520 +buffer to be reallocated in order to accommodate the new data. As a
1.1521 +result, MaxLength() and Ptr() may return different values afterwards,
1.1522 +and any existing raw pointers to into the descriptor data may be
1.1523 +invalidated.
1.1524 +
1.1525 +@param aVal The 64 bit integer value. This is treated as an unsigned
1.1526 + value for all builds.
1.1527 +@param aRadix The number system representation for the 64 bit integer.
1.1528 +
1.1529 +@leave KErrNoMemory if the underlying buffer needs to be
1.1530 +grown and there are insufficient resources to do so
1.1531 +*/
1.1532 +EXPORT_C void LString16::NumL(TUint64 aVal, TRadix aRadix)
1.1533 + {
1.1534 + Zero();
1.1535 + AppendNumL(aVal, aRadix);
1.1536 + }
1.1537 +
1.1538 +/**
1.1539 +Formats and copies text into this descriptor, replacing any existing data.
1.1540 +
1.1541 +The length of this descriptor is set to reflect the new data.
1.1542 +
1.1543 +The function takes a format string and a variable number of arguments.
1.1544 +The format string contains literal text embedded with directives for converting
1.1545 +the trailing list of arguments into text.
1.1546 +
1.1547 +The embedded directives are character sequences prefixed with the '%' character.
1.1548 +The literal text is simply copied into this descriptor unaltered while
1.1549 +the '%' directives are used to convert successive arguments from the
1.1550 +trailing list.
1.1551 +
1.1552 +The resulting stream of literal text and converted arguments is copied into
1.1553 +this descriptor.
1.1554 +
1.1555 +The syntax of the embedded directives follows one of four general patterns.
1.1556 +
1.1557 +Note that formatting of single numerical values can be achieved more
1.1558 +conveniently using the Num() and NumUC() member functions of this class.
1.1559 +
1.1560 +The full description of the syntax of a format string cannot be included here.
1.1561 +For full details, navigate to the Symbian OS guide, and follow the hierarchy of links:
1.1562 +
1.1563 +@code
1.1564 +Symbian OS Guide
1.1565 + Base
1.1566 + Using User Library (E32)
1.1567 + Buffers and Strings
1.1568 + Using Descriptors
1.1569 + How to Use Descriptors
1.1570 + Format string syntax
1.1571 +@endcode
1.1572 +
1.1573 +This leaving variant of the standard, non-leaving descriptor method
1.1574 +differs in that this operation may cause the string descriptor's heap
1.1575 +buffer to be reallocated in order to accommodate the new data. As a
1.1576 +result, MaxLength() and Ptr() may return different values afterwards,
1.1577 +and any existing raw pointers to into the descriptor data may be
1.1578 +invalidated.
1.1579 +
1.1580 +@param aFmt The descriptor containing the format string.
1.1581 + The TRefByValue class provides a constructor which takes a
1.1582 + TDesC8 type.
1.1583 +
1.1584 +@param ... A variable number of arguments to be converted to text as
1.1585 + dictated by the format string.
1.1586 +
1.1587 +@panic USER 12 if the format string has incorrect syntax.
1.1588 +
1.1589 +@leave KErrNoMemory if the underlying buffer needs to be
1.1590 +grown and there are insufficient resources to do so
1.1591 +
1.1592 +@see TDes16::Num()
1.1593 +@see TDes16::NumUC()
1.1594 +*/
1.1595 +EXPORT_C void LString16::FormatL(TRefByValue<const TDesC16> aFmt,...)
1.1596 + {
1.1597 + VA_LIST list;
1.1598 + VA_START(list,aFmt);
1.1599 + FormatListL(aFmt,list);
1.1600 + }
1.1601 +
1.1602 +/**
1.1603 +Formats and copies text into this descriptor, replacing any existing data.
1.1604 +
1.1605 +The length of this descriptor is set to reflect the new data.
1.1606 +
1.1607 +The behaviour of this function is the same as FormatL(). In practice, it is
1.1608 +better and easier to use FormatL(), passing a variable number of arguments
1.1609 +as required by the format string.
1.1610 +
1.1611 +This leaving variant of the standard, non-leaving descriptor method
1.1612 +differs in that this operation may cause the string descriptor's heap
1.1613 +buffer to be reallocated in order to accommodate the new data. As a
1.1614 +result, MaxLength() and Ptr() may return different values afterwards,
1.1615 +and any existing raw pointers to into the descriptor data may be
1.1616 +invalidated.
1.1617 +
1.1618 +@param aFmt The descriptor containing the format string.
1.1619 +@param aList A pointer to an argument list.
1.1620 +
1.1621 +@leave KErrNoMemory if the underlying buffer needs to be
1.1622 +grown and there are insufficient resources to do so
1.1623 +
1.1624 +@see TDes16::Format()
1.1625 +@see VA_LIST
1.1626 +*/
1.1627 +EXPORT_C void LString16::FormatListL(const TDesC16& aFmt,VA_LIST aList)
1.1628 + {
1.1629 + Zero();
1.1630 + AppendFormatListL(aFmt, aList);
1.1631 + }
1.1632 +
1.1633 +/**
1.1634 +Appends data onto the end of this descriptor's data and justifies it.
1.1635 +
1.1636 +The source of the appended data is an existing descriptor.
1.1637 +
1.1638 +The target area is considered to be an area of specified width, immediately
1.1639 +following this descriptor's existing data. Source data is copied into, and
1.1640 +aligned within this target area according to the specified alignment instruction.
1.1641 +
1.1642 +If the length of the target area is larger than the length of the source,
1.1643 +then spare space within the target area is padded with the fill character.
1.1644 +
1.1645 +This leaving variant of the standard, non-leaving descriptor method
1.1646 +differs in that this operation may cause the string descriptor's heap
1.1647 +buffer to be reallocated in order to accommodate the new data. As a
1.1648 +result, MaxLength() and Ptr() may return different values afterwards,
1.1649 +and any existing raw pointers to into the descriptor data may be
1.1650 +invalidated.
1.1651 +
1.1652 +@param aDes A 16-bit non-modifiable descriptor containing the source
1.1653 + data. The length of the data to be copied is the smaller of:
1.1654 + the length of the source descriptor, and
1.1655 + the width of the target area (only if this is not the
1.1656 + explicit negative value KDefaultJustifyWidth).
1.1657 +
1.1658 +@param aWidth The width of the target area. If this has the specific
1.1659 + negative value KDefaultJustifyWidth, then the width is
1.1660 + re-set to the length of the data source.
1.1661 +
1.1662 +@param aAlignment The alignment of the data within the target area.
1.1663 +
1.1664 +@param aFill The fill character used to pad the target area.
1.1665 +
1.1666 +@leave KErrNoMemory if the underlying buffer needs to be
1.1667 +grown and there are insufficient resources to do so
1.1668 +
1.1669 +@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
1.1670 +*/
1.1671 +EXPORT_C void LString16::AppendJustifyL(const TDesC16& Des,TInt aWidth,TAlign aAlignment,TChar aFill)
1.1672 + {
1.1673 +
1.1674 + TInt width = (aWidth == KDefaultJustifyWidth ? Des.Length() : aWidth);
1.1675 + ReserveFreeCapacityGrowExponentialL(width);
1.1676 + RBuf16::AppendJustify(Des, aWidth, aAlignment, aFill);
1.1677 + }
1.1678 +
1.1679 +/**
1.1680 +Appends data onto the end of this descriptor's data and justifies it.
1.1681 +
1.1682 +The source of the appended data is an existing descriptor.
1.1683 +
1.1684 +The target area is considered to be an area of specified width, immediately
1.1685 +following this descriptor's existing data. Source data is copied into, and
1.1686 +aligned within this target area according to the specified alignment instruction.
1.1687 +
1.1688 +If the length of the target area is larger than the length of the source,
1.1689 +then spare space within the target area is padded with the fill character.
1.1690 +
1.1691 +This leaving variant of the standard, non-leaving descriptor method
1.1692 +differs in that this operation may cause the string descriptor's heap
1.1693 +buffer to be reallocated in order to accommodate the new data. As a
1.1694 +result, MaxLength() and Ptr() may return different values afterwards,
1.1695 +and any existing raw pointers to into the descriptor data may be
1.1696 +invalidated.
1.1697 +
1.1698 +@param aDes An 8-bit non-modifiable descriptor containing the source data.
1.1699 +
1.1700 +@param aLength The length of data to be copied from the source descriptor.
1.1701 + If this is greater than the width of the target area, then
1.1702 + the length of data copied is limited to the width.
1.1703 + The length of data to be copied must not be greater than
1.1704 + the length of the source descriptor. Note that this
1.1705 + condition is not automatically tested.
1.1706 +
1.1707 +@param aWidth The width of the target area. If this has the specific negative
1.1708 + value KDefaultJustifyWidth, then the width is
1.1709 + re-set to the length of the data source.
1.1710 +
1.1711 +@param aAlignment The alignment of the data within the target area.
1.1712 +
1.1713 +@param aFill The fill character used to pad the target area.
1.1714 +
1.1715 +@leave KErrNoMemory if the underlying buffer needs to be
1.1716 +grown and there are insufficient resources to do so
1.1717 +
1.1718 +@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
1.1719 +*/
1.1720 +EXPORT_C void LString16::AppendJustifyL(const TDesC16& Des,TInt aLength,TInt aWidth,TAlign aAlignment,TChar aFill)
1.1721 + {
1.1722 +
1.1723 + TInt width = (aWidth == KDefaultJustifyWidth ? aLength : aWidth);
1.1724 + ReserveFreeCapacityGrowExponentialL(width);
1.1725 +
1.1726 + RBuf16::AppendJustify(Des, aLength, aWidth, aAlignment, aFill);
1.1727 + }
1.1728 +
1.1729 +/**
1.1730 +Appends a zero terminated string onto the end of this descriptor's data and
1.1731 +justifies it.
1.1732 +
1.1733 +The zero terminator is not copied.
1.1734 +
1.1735 +The target area is considered to be an area of specified width, immediately
1.1736 +following this descriptor's existing data. Source data is copied into, and
1.1737 +aligned within, this target area according to the specified alignment instruction.
1.1738 +
1.1739 +If the length of the target area is larger than the length of the source,
1.1740 +then spare space within the target area is padded with the fill character.
1.1741 +
1.1742 +This leaving variant of the standard, non-leaving descriptor method
1.1743 +differs in that this operation may cause the string descriptor's heap
1.1744 +buffer to be reallocated in order to accommodate the new data. As a
1.1745 +result, MaxLength() and Ptr() may return different values afterwards,
1.1746 +and any existing raw pointers to into the descriptor data may be
1.1747 +invalidated.
1.1748 +
1.1749 +@param aZeroTerminatedString A pointer to a zero terminated string The length of the data
1.1750 + to be copied is the smaller of: the length of the string (excluding the zero
1.1751 + terminator), the width of the target area (only if this is not the explicit
1.1752 + negative value KDefaultJustifyWidth).
1.1753 +
1.1754 +@param aWidth The width of the target area. If this has the specific negative
1.1755 + value KDefaultJustifyWidth, then the width is re-set to the length of the
1.1756 + zero terminated string (excluding the zero terminator).
1.1757 +
1.1758 +@param aAlignment The alignment of the data within the target area.
1.1759 +
1.1760 +@param aFill The fill character used to pad the target area.
1.1761 +
1.1762 +@leave KErrNoMemory if the underlying buffer needs to be
1.1763 +grown and there are insufficient resources to do so
1.1764 +
1.1765 +@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
1.1766 +*/
1.1767 +EXPORT_C void LString16::AppendJustifyL(const TUint16* aZeroTerminatedString,TInt aWidth,TAlign aAlignment,TChar aFill)
1.1768 + {
1.1769 +
1.1770 + TInt width = (aWidth == KDefaultJustifyWidth ? User::StringLength(aZeroTerminatedString) : aWidth);
1.1771 + ReserveFreeCapacityGrowExponentialL(width);
1.1772 +
1.1773 + RBuf16::AppendJustify(aZeroTerminatedString, aWidth, aAlignment, aFill);
1.1774 +
1.1775 + }
1.1776 +
1.1777 +/**
1.1778 +Appends data onto the end of this descriptor's data and justifies it.
1.1779 +
1.1780 +The source of the appended data is a memory location.
1.1781 +
1.1782 +The target area is considered to be an area of specified width, immediately
1.1783 +following this descriptor's existing data. Source data is copied into, and
1.1784 +aligned within, this target area according to the specified alignment instruction.
1.1785 +
1.1786 +If the length of the target area is larger than the length of the source,
1.1787 +then spare space within the target area is padded with the fill character.
1.1788 +
1.1789 +This leaving variant of the standard, non-leaving descriptor method
1.1790 +differs in that this operation may cause the string descriptor's heap
1.1791 +buffer to be reallocated in order to accommodate the new data. As a
1.1792 +result, MaxLength() and Ptr() may return different values afterwards,
1.1793 +and any existing raw pointers to into the descriptor data may be
1.1794 +invalidated.
1.1795 +
1.1796 +@param aString A pointer to a source memory location.
1.1797 +
1.1798 +@param aLength The length of data to be copied. If this is greater than the
1.1799 + width of the target area, then the length of data copied is
1.1800 + limited to the width.
1.1801 +
1.1802 +@param aWidth The width of the target area. If this has the specific negative
1.1803 + value KDefaultJustifyWidth, then the width is
1.1804 + re-set to the length of the data source.
1.1805 +
1.1806 +@param aAlignment The alignment of the data within the target area.
1.1807 +
1.1808 +@param aFill The fill character used to pad the target area.
1.1809 +
1.1810 +@leave KErrNoMemory if the underlying buffer needs to be
1.1811 +grown and there are insufficient resources to do so
1.1812 +
1.1813 +@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
1.1814 +
1.1815 +@panic USER 17 if aLength is negative.
1.1816 +*/
1.1817 +EXPORT_C void LString16::AppendJustifyL(const TUint16* aString,TInt aLength,TInt aWidth,TAlign aAlignment,TChar aFill)
1.1818 + {
1.1819 +
1.1820 + TInt width = (aWidth == KDefaultJustifyWidth ? aLength : aWidth);
1.1821 + ReserveFreeCapacityGrowExponentialL(width);
1.1822 +
1.1823 + RBuf16::AppendJustify(aString, aLength, aWidth, aAlignment, aFill);
1.1824 + }
1.1825 +
1.1826 +/**
1.1827 +Converts the specified unsigned integer into a fixed width character
1.1828 +representation based on the specified number system and appends the conversion
1.1829 +onto the end of this descriptor's data.
1.1830 +
1.1831 +The length of this descriptor is incremented to reflect the new content.
1.1832 +
1.1833 +The function generates the exact number of specified characters, either
1.1834 +padding to the left with character zeroes or discarding low order characters
1.1835 +as necessary.
1.1836 +
1.1837 +When a hexadecimal conversion is specified, hexadecimal characters are in
1.1838 +upper case.
1.1839 +
1.1840 +This leaving variant of the standard, non-leaving descriptor method
1.1841 +differs in that this operation may cause the string descriptor's heap
1.1842 +buffer to be reallocated in order to accommodate the new data. As a
1.1843 +result, MaxLength() and Ptr() may return different values afterwards,
1.1844 +and any existing raw pointers to into the descriptor data may be
1.1845 +invalidated.
1.1846 +
1.1847 +@param aVal The unsigned integer value.
1.1848 +@param aRadix The number system representation for the unsigned integer.
1.1849 +@param aWidth The number of characters: to be used to contain the conversion,
1.1850 + to be appended to this descriptor.
1.1851 +
1.1852 +@leave KErrNoMemory if the underlying buffer needs to be
1.1853 +grown and there are insufficient resources to do so
1.1854 +
1.1855 +*/
1.1856 +EXPORT_C void LString16::AppendNumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth)
1.1857 + {
1.1858 + ReserveFreeCapacityGrowExponentialL(aWidth);
1.1859 + RBuf16::AppendNumFixedWidthUC(aVal, aRadix, aWidth);
1.1860 + }
1.1861 +
1.1862 +/**
1.1863 +Converts the specified 64 bit integer into a character representation
1.1864 +based on the specified number system and appends the conversion onto the end
1.1865 +of this descriptor's data.
1.1866 +
1.1867 +The length of this descriptor is incremented to reflect the new content.
1.1868 +
1.1869 +When a hexadecimal conversion is specified, hexadecimal characters are in
1.1870 +upper case.
1.1871 +
1.1872 +This leaving variant of the standard, non-leaving descriptor method
1.1873 +differs in that this operation may cause the string descriptor's heap
1.1874 +buffer to be reallocated in order to accommodate the new data. As a
1.1875 +result, MaxLength() and Ptr() may return different values afterwards,
1.1876 +and any existing raw pointers to into the descriptor data may be
1.1877 +invalidated.
1.1878 +
1.1879 +@param aVal The 64 bit integer value. This is always treated as an unsigned
1.1880 + value.
1.1881 +@param aRadix The number system representation for the 64 bit integer. If no
1.1882 + explicit value is specified, then EDecimal is the default.
1.1883 +
1.1884 +@leave KErrNoMemory if the underlying buffer needs to be
1.1885 +grown and there are insufficient resources to do so
1.1886 +*/
1.1887 +EXPORT_C void LString16::AppendNumUCL(TUint64 aVal, TRadix aRadix)
1.1888 + {
1.1889 + ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize);
1.1890 + RBuf16::AppendNumUC(aVal, aRadix);
1.1891 + }
1.1892 +
1.1893 +/**
1.1894 +Converts the specified floating point number into a character representation
1.1895 +and appends the conversion onto the end of this descriptor's data.
1.1896 +
1.1897 +The length of this descriptor is incremented to reflect the new content.
1.1898 +
1.1899 +The character representation of the real number is dictated by the specified
1.1900 +format.
1.1901 +
1.1902 +This leaving variant of the standard, non-leaving descriptor method
1.1903 +differs in that this operation may cause the string descriptor's heap
1.1904 +buffer to be reallocated in order to accommodate the new data. As a
1.1905 +result, MaxLength() and Ptr() may return different values afterwards,
1.1906 +and any existing raw pointers to into the descriptor data may be
1.1907 +invalidated.
1.1908 +
1.1909 +@param aVal The floating point number to be converted.
1.1910 +@param aFormat The format of the conversion.
1.1911 +
1.1912 +@return If the conversion is successful, the length of this descriptor. If
1.1913 + the conversion fails, a negative value indicating the cause of failure.
1.1914 + In addition, extra information on the cause of the failure may be
1.1915 + appended onto this descriptor. The possible values and their meaning
1.1916 + are:
1.1917 +
1.1918 + 1.KErrArgument - the supplied floating point number is not a valid
1.1919 + number. The three characters NaN are appended to this descriptor.
1.1920 +
1.1921 + 2.KErrOverflow - the number is too large to represent.
1.1922 + 2.1 For positive overflow, the three characters Inf are appended
1.1923 + to this descriptor.
1.1924 + 2.2 For negative overflow, the four characters -Inf are appended
1.1925 + to this descriptor.
1.1926 +
1.1927 + 3.KErrUnderflow - the number is too small to represent.
1.1928 + 3.1 For positive underflow, the three characters Inf are appended
1.1929 + to this descriptor.
1.1930 + 3.2 For negative underflow, the four characters -Inf are appended
1.1931 + to this descriptor.
1.1932 +
1.1933 + 4.KErrGeneral - the conversion cannot be completed. There are a
1.1934 + number of possible reasons for this, but the most common is:
1.1935 + 4.1 The character representation format (i.e. the format type), as
1.1936 + defined in the TRealFormat object is not recognised.
1.1937 +
1.1938 +@leave KErrNoMemory if the underlying buffer needs to be
1.1939 +grown and there are insufficient resources to do so
1.1940 +*/
1.1941 +EXPORT_C TInt LString16::AppendNumL(TReal aVal,const TRealFormat& aFormat)
1.1942 + {
1.1943 + ReserveFreeCapacityGrowExponentialL(aFormat.iWidth + 1 + KDefaultExpandSize);
1.1944 + return RBuf16::AppendNum(aVal, aFormat);
1.1945 + }
1.1946 +
1.1947 +/**
1.1948 +Converts the 64-bit signed integer into a decimal character representation
1.1949 +and appends the conversion onto the end of this descriptor's data.
1.1950 +
1.1951 +The length of this descriptor is incremented to reflect the new content.
1.1952 +
1.1953 +If the integer is negative, the character representation is prefixed by a
1.1954 +minus sign.
1.1955 +
1.1956 +This leaving variant of the standard, non-leaving descriptor method
1.1957 +differs in that this operation may cause the string descriptor's heap
1.1958 +buffer to be reallocated in order to accommodate the new data. As a
1.1959 +result, MaxLength() and Ptr() may return different values afterwards,
1.1960 +and any existing raw pointers to into the descriptor data may be
1.1961 +invalidated.
1.1962 +
1.1963 +@param aVal The 64-bit signed integer value.
1.1964 +
1.1965 +@leave KErrNoMemory if the underlying buffer needs to be
1.1966 +grown and there are insufficient resources to do so
1.1967 +*/
1.1968 +EXPORT_C void LString16::AppendNumL(TInt64 aVal)
1.1969 + {
1.1970 + ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize);
1.1971 + RBuf16::AppendNum(aVal);
1.1972 + }
1.1973 +
1.1974 +/**
1.1975 +Converts the specified 64 bit integer into a character representation
1.1976 +based on the specified number system and appends the conversion onto the end
1.1977 +of this descriptor's data.
1.1978 +
1.1979 +The length of this descriptor is incremented to reflect the new content.
1.1980 +
1.1981 +When a hexadecimal conversion is specified, hexadecimal characters are in
1.1982 +lower case.
1.1983 +
1.1984 +This leaving variant of the standard, non-leaving descriptor method
1.1985 +differs in that this operation may cause the string descriptor's heap
1.1986 +buffer to be reallocated in order to accommodate the new data. As a
1.1987 +result, MaxLength() and Ptr() may return different values afterwards,
1.1988 +and any existing raw pointers to into the descriptor data may be
1.1989 +invalidated.
1.1990 +
1.1991 +@param aVal The 64 bit integer value. This is always treated as an unsigned
1.1992 + value.
1.1993 +@param aRadix The number system representation for the 64 bit integer.
1.1994 +
1.1995 +@leave KErrNoMemory if the underlying buffer needs to be
1.1996 +grown and there are insufficient resources to do so
1.1997 +*/
1.1998 +EXPORT_C void LString16::AppendNumL(TUint64 aVal, TRadix aRadix)
1.1999 + {
1.2000 + ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize);
1.2001 + RBuf16::AppendNum(aVal, aRadix);
1.2002 + }
1.2003 +
1.2004 +/**
1.2005 +Formats and appends text onto the end of this descriptor's data.
1.2006 +
1.2007 +The length of this descriptor is incremented to reflect the new content.
1.2008 +
1.2009 +The function takes a format string and a variable number of arguments.
1.2010 +The format string contains literal text, embedded with directives,
1.2011 +for converting the trailing list of arguments into text.
1.2012 +
1.2013 +The embedded directives are character sequences prefixed with the '%' character.
1.2014 +The literal text is simply copied into this descriptor unaltered while
1.2015 +the '%' directives are used to convert successive arguments from the
1.2016 +trailing list. See the description of the Format() function.
1.2017 +
1.2018 +Literal text is appended on a character by character basis, and the
1.2019 +underlying buffer is grown as necessary to accommodate it.
1.2020 +
1.2021 +Text converted from a trailing argument is appended as a complete
1.2022 +string, and the underlying buffer is grown as necessary to accommodate
1.2023 +it.
1.2024 +
1.2025 +This leaving variant of the standard, non-leaving descriptor method
1.2026 +differs in that this operation may cause the string descriptor's heap
1.2027 +buffer to be reallocated in order to accommodate the new data. As a
1.2028 +result, MaxLength() and Ptr() may return different values afterwards,
1.2029 +and any existing raw pointers to into the descriptor data may be
1.2030 +invalidated.
1.2031 +
1.2032 +@param aFmt The 16-bit non-modifiable descriptor containing the
1.2033 + format string. The TRefByValue class provides a
1.2034 + constructor which takes a TDesC16 type.
1.2035 +
1.2036 +@param ... A variable number of arguments to be converted to text
1.2037 + as dictated by the format string.
1.2038 +
1.2039 +@leave KErrNoMemory if the underlying buffer needs to be
1.2040 +grown and there are insufficient resources to do so
1.2041 +
1.2042 +@panic USER 12 if the format string has incorrect syntax.
1.2043 +
1.2044 +@see TDes16::Format()
1.2045 +@see TDes16Overflow::Overflow()
1.2046 +*/
1.2047 +EXPORT_C void LString16::AppendFormatL(TRefByValue<const TDesC16> aFmt,...)
1.2048 + {
1.2049 + VA_LIST list;
1.2050 + VA_START(list,aFmt);
1.2051 + AppendFormatListL(aFmt,list);
1.2052 + }
1.2053 +
1.2054 +class TRetryOverflow16 : public TDes16Overflow
1.2055 + {
1.2056 +public:
1.2057 + TRetryOverflow16() : iOverflow(EFalse)
1.2058 + {
1.2059 + }
1.2060 +
1.2061 + virtual void Overflow(TDes16& /*aDes*/)
1.2062 + {
1.2063 + iOverflow = ETrue;
1.2064 + }
1.2065 +
1.2066 + TBool iOverflow;
1.2067 + };
1.2068 +
1.2069 +/**
1.2070 +Formats and appends text onto the end of this descriptor's data.
1.2071 +
1.2072 +The length of this descriptor is incremented to reflect the new content.
1.2073 +
1.2074 +The behaviour of this function is the same as
1.2075 +AppendFormatL(TRefByValue<const TDesC16> aFmt,TDes16Overflow *aOverflowHandler,...).
1.2076 +In practice, it is better and easier to use AppendFormat(), passing a variable number of
1.2077 +arguments as required by the format string.
1.2078 +
1.2079 +This leaving variant of the standard, non-leaving descriptor method
1.2080 +differs in that this operation may cause the string descriptor's heap
1.2081 +buffer to be reallocated in order to accommodate the new data. As a
1.2082 +result, MaxLength() and Ptr() may return different values afterwards,
1.2083 +and any existing raw pointers to into the descriptor data may be
1.2084 +invalidated.
1.2085 +
1.2086 +@param aFmt The descriptor containing the format string.
1.2087 +@param aList A pointer to an argument list.
1.2088 +
1.2089 +@leave KErrNoMemory if the underlying buffer needs to be
1.2090 +grown and there are insufficient resources to do so
1.2091 +
1.2092 +@see TDes16::AppendFormat
1.2093 +@see VA_LIST
1.2094 +*/
1.2095 +EXPORT_C void LString16::AppendFormatListL(const TDesC16& aFmt,VA_LIST aList)
1.2096 + {
1.2097 + ReserveFreeCapacityGrowExponentialL(aFmt.Length() + KDefaultExpandSize); // We use aFmt as a hint
1.2098 + for (;;)
1.2099 + {
1.2100 + TInt before = Length();
1.2101 + TRetryOverflow16 overflow;
1.2102 + RBuf16::AppendFormatList(aFmt, aList, &overflow);
1.2103 + if (overflow.iOverflow)
1.2104 + {
1.2105 + SetLengthL(before); // Can't leave
1.2106 + ReserveCapacityGrowExponentialL();
1.2107 + }
1.2108 + else
1.2109 + {
1.2110 + break;
1.2111 + }
1.2112 + }
1.2113 + }
1.2114 +
1.2115 +
1.2116 +/**
1.2117 +Unlinks and transfers ownership of the specified 16-bit resizable descriptor's
1.2118 +buffer to this object. The source descriptor is detached from the buffer.
1.2119 +
1.2120 +@param aString The source 16-bit resizable buffer. The ownership of this
1.2121 + object's buffer is to be transferred.
1.2122 +
1.2123 +@see RBuf16::Close()
1.2124 +*/
1.2125 +EXPORT_C void LString16::Assign(const LString16& aString)
1.2126 + {
1.2127 + // free any previously owned resource
1.2128 + Reset();
1.2129 +
1.2130 + RBuf16::Assign(aString);
1.2131 + // unlink buffer from original descriptor
1.2132 + new (const_cast<LString16*>(&aString)) LString16();
1.2133 + }
1.2134 +
1.2135 +
1.2136 +/**
1.2137 +Transfers ownership of the specified 16-bit resizable descriptor's
1.2138 +buffer to this object. The source descriptor is detached from the buffer.
1.2139 +
1.2140 +@param aRBuf The source 16-bit resizable buffer. The ownership of this
1.2141 + object's buffer is to be transferred.
1.2142 +
1.2143 +@see RBuf16::Assign()
1.2144 +*/
1.2145 +
1.2146 +EXPORT_C void LString16::Assign(const RBuf16& aRBuf)
1.2147 + {
1.2148 + // free any previously owned resource
1.2149 + Reset();
1.2150 +
1.2151 + RBuf16::Assign(aRBuf);
1.2152 +
1.2153 + // reset the RBuf;
1.2154 + new (const_cast<RBuf16*>(&aRBuf)) RBuf16();
1.2155 + }
1.2156 +
1.2157 +
1.2158 +/**
1.2159 +Transfers ownership of the specified 16-bit resizable descriptor's this object.
1.2160 +
1.2161 +@param aHBuf The heap descriptor to be transferred to this object.
1.2162 + The ownership of this object's buffer is to be transferred.
1.2163 +
1.2164 +@see RBuf16::Assign()
1.2165 +*/
1.2166 +EXPORT_C void LString16::Assign(HBufC16* aHBuf)
1.2167 + {
1.2168 + // free any previously owned resource
1.2169 + Reset();
1.2170 +
1.2171 + RBuf16::Assign(aHBuf);
1.2172 + }
1.2173 +
1.2174 +
1.2175 +/**
1.2176 +Assigns ownership of the specified allocated memory to this object.
1.2177 +
1.2178 +@param aHeapCell The allocated memory to be assigned to this object.
1.2179 + This pointer can be NULL, which means that a zero length
1.2180 + 16-bit resizable buffer descriptor is created.
1.2181 +
1.2182 +@param aMaxLength The maximum length of the descriptor.
1.2183 +
1.2184 +@panic USER 8 If the specified maximum length is greater then the size of the
1.2185 + allocated heap cell, or the specified maximum length is NOT
1.2186 + zero when the pointer to the heap cell is NULL.
1.2187 +
1.2188 +@see RBuf16::Close()
1.2189 +@see RBuf16::Assign()
1.2190 +*/
1.2191 +EXPORT_C void LString16::Assign(TUint16* aHeapCell, TInt aMaxLength)
1.2192 + {
1.2193 + // free any previously owned resource
1.2194 + Reset();
1.2195 +
1.2196 + RBuf16::Assign(aHeapCell, aMaxLength);
1.2197 + }
1.2198 +
1.2199 +
1.2200 +/**
1.2201 +Transfers ownership of the specified 16-bit resizable descriptor's this object.
1.2202 +
1.2203 +@param aHeapCell The allocated memory to be assigned to this object.
1.2204 +
1.2205 +@param aLength The length of the descriptor.
1.2206 +
1.2207 +@param aMaxLength The maximum length of the descriptor.
1.2208 +
1.2209 +@panic USER 8 If the specified maximum length is greater then the size of the
1.2210 + allocated heap cell, or the specified length is greater then
1.2211 + the specified maximum length, or the specified maximum length
1.2212 + is NOT zero when the pointer to the heap cell is NULL.
1.2213 +
1.2214 +@see RBuf16::Close()
1.2215 +@see RBuf16::Assign()
1.2216 +*/
1.2217 +EXPORT_C void LString16::Assign(TUint16* aHeapCell,TInt aLength,TInt aMaxLength)
1.2218 + {
1.2219 + // free any previously owned resource
1.2220 + Reset();
1.2221 +
1.2222 + RBuf16::Assign(aHeapCell, aLength, aMaxLength);
1.2223 + }
1.2224 +
1.2225 +/**
1.2226 +Creates a 16-bit resizable buffer descriptor that has been initialised with
1.2227 +data from the specified read stream; leaves on failure.
1.2228 +
1.2229 +Data is assigned to the new descriptor from the specified stream.
1.2230 +This variant assumes that the stream contains the length of the data followed
1.2231 +by the data itself.
1.2232 +
1.2233 +The function is implemented by calling the HBufC16::NewL(RReadStream&,TInt)
1.2234 +variant and then assigning the resulting heap descriptor using
1.2235 +the RBuf16::Assign(HBufC16*) variant. The comments that describe
1.2236 +the HBufC16::NewL() variant also apply to this RBuf16::CreateL() function.
1.2237 +
1.2238 +The function may leave with one of the system-wide error codes, specifically
1.2239 +KErrOverflow, if the length of the data as read from the stream is greater than
1.2240 +the upper limit as specified by the aMaxLength parameter.
1.2241 +
1.2242 +@param aStream The stream from which the data length and the data to be
1.2243 + assigned to the new descriptor, are taken.
1.2244 +@param aMaxLength The upper limit on the length of data that the descriptor is
1.2245 + to represent. The value of this parameter must be non-negative
1.2246 + otherwise the underlying function will panic.
1.2247 +*/
1.2248 +EXPORT_C void LString16::CreateL(RReadStream &aStream,TInt aMaxLength)
1.2249 + {
1.2250 + Reset();
1.2251 + Assign(HBufC16::NewL(aStream,aMaxLength));
1.2252 + }
1.2253 +
1.2254 +/**
1.2255 +Appends data onto the end of this descriptor's data.
1.2256 +
1.2257 +The length of this descriptor is incremented to reflect the new content.
1.2258 +
1.2259 +This leaving variant of the standard, non-leaving descriptor method
1.2260 +differs in that this operation may cause the string descriptor's heap
1.2261 +buffer to be reallocated in order to accommodate the new data. As a
1.2262 +result, MaxLength() and Ptr() may return different values afterwards,
1.2263 +and any existing raw pointers to into the descriptor data may be
1.2264 +invalidated.
1.2265 +
1.2266 +@param aZeroTerminatedString A pointer to a zero terminated string .
1.2267 +@leave KErrNoMemory if the underlying buffer needs to be
1.2268 +grown and there are insufficient resources to do so
1.2269 +
1.2270 +@see LString16::AppendL
1.2271 +*/
1.2272 +EXPORT_C LString16& LString16::operator+=(const TUint16* aZeroTerminatedString)
1.2273 + {
1.2274 + AppendL(aZeroTerminatedString,User::StringLength(aZeroTerminatedString));
1.2275 + return *this;
1.2276 + }
1.2277 +/**
1.2278 +Appends data onto the end of this descriptor's data.
1.2279 +
1.2280 +The length of this descriptor is incremented to reflect the new content.
1.2281 +
1.2282 +This leaving variant of the standard, non-leaving descriptor method
1.2283 +differs in that this operation may cause the string descriptor's heap
1.2284 +buffer to be reallocated in order to accommodate the new data. As a
1.2285 +result, MaxLength() and Ptr() may return different values afterwards,
1.2286 +and any existing raw pointers to into the descriptor data may be
1.2287 +invalidated.
1.2288 +
1.2289 +@param aZeroTerminatedString A pointer to the data to be copied.
1.2290 +
1.2291 +@leave KErrNoMemory if the underlying buffer needs to be
1.2292 +grown and there are insufficient resources to do so
1.2293 +
1.2294 +@panic USER 17 if aLength is negative.
1.2295 +*/
1.2296 +EXPORT_C void LString16::AppendL(const TUint16* aZeroTerminatedString)
1.2297 + {
1.2298 + AppendL(aZeroTerminatedString,User::StringLength(aZeroTerminatedString));
1.2299 + }
1.2300 +
1.2301 +/**
1.2302 +Constructor to create a 16-bit resizable string descriptor containing
1.2303 +a copy of the specified (source) zero-terminated wide character string data, or leave
1.2304 +on failure.
1.2305 +
1.2306 +The constructor allocates sufficient memory so that this string
1.2307 +descriptor's maximum length is the same as the length of the source
1.2308 +string. Both the current length and the maximum length of this string
1.2309 +descriptor are set to the length of the source string.
1.2310 +
1.2311 +The data contained in the source string is copied into this string
1.2312 +descriptor. The zero terminator is not copied.
1.2313 +
1.2314 +@param aWideCharStr A pointer to a zero-terminated wide character string
1.2315 +
1.2316 +@leave KErrNoMemory If there is insufficient memory.
1.2317 +
1.2318 +@see LString16::CopyL
1.2319 +*/
1.2320 +EXPORT_C LString16::LString16(const wchar_t* aWideCharStr)
1.2321 + : iReserved(0)
1.2322 + {
1.2323 + CopyL(reinterpret_cast<const TUint16*>(aWideCharStr));
1.2324 + }
1.2325 +
1.2326 +/**
1.2327 +Copies data into this 16-bit string descriptor, replacing any existing
1.2328 +data, and expanding its heap buffer to accommodate if necessary.
1.2329 +
1.2330 +The length of this descriptor is set to reflect the new data.
1.2331 +
1.2332 +This operation may cause the target string descriptor's heap buffer to
1.2333 +be reallocated in order to accommodate the new data. As a result,
1.2334 +MaxLength() and Ptr() may return different values afterwards, and any
1.2335 +existing raw pointers to into the descriptor data may be invalidated.
1.2336 +
1.2337 +Note that the automatic resizing performed is a change to the
1.2338 +functionality of this operation compared to other descriptor
1.2339 +classes. This change is only active on objects directly declared
1.2340 +LString16; when LString16 instances are instead manipulated via
1.2341 +references to TDes16 or TDesC16, the standard (non-resizing, panicing)
1.2342 +variant is invoked.
1.2343 +
1.2344 +@param aWideCharStr A pointer to a wide character zero-terminated string
1.2345 +
1.2346 +@return A reference to this 16-bit string descriptor.
1.2347 +
1.2348 +@leave KErrNoMemory If the heap buffer of the string descriptor being
1.2349 + assigned to needs to be expanded, but there is
1.2350 + insufficient memory to do so
1.2351 +
1.2352 +@see LString16::CopyL
1.2353 +*/
1.2354 +EXPORT_C LString16& LString16::operator=(const wchar_t* aWideCharStr)
1.2355 + {
1.2356 + CopyL(reinterpret_cast<const TUint16*>(aWideCharStr));
1.2357 + return *this;
1.2358 + }
1.2359 +
1.2360 +/**
1.2361 +Appends data onto the end of this descriptor's data.
1.2362 +
1.2363 +The length of this descriptor is incremented to reflect the new content.
1.2364 +
1.2365 +This leaving variant of the standard, non-leaving descriptor method
1.2366 +differs in that this operation may cause the string descriptor's heap
1.2367 +buffer to be reallocated in order to accommodate the new data. As a
1.2368 +result, MaxLength() and Ptr() may return different values afterwards,
1.2369 +and any existing raw pointers to into the descriptor data may be
1.2370 +invalidated.
1.2371 +
1.2372 +@param aWideCharStr A pointer to a wide character zero terminated string .
1.2373 +@leave KErrNoMemory if the underlying buffer needs to be
1.2374 +grown and there are insufficient resources to do so
1.2375 +
1.2376 +@see LString16::AppendL
1.2377 +*/
1.2378 +EXPORT_C LString16& LString16::operator+=(const wchar_t* aWideCharStr)
1.2379 + {
1.2380 + AppendL(reinterpret_cast<const TUint16*>(aWideCharStr),User::StringLength(reinterpret_cast<const TUint16*>(aWideCharStr)));
1.2381 + return *this;
1.2382 + }
1.2383 +
1.2384 +/**
1.2385 +Copies data into this 16-bit string descriptor, replacing any existing
1.2386 +data, and expanding its heap buffer to accommodate if necessary.
1.2387 +
1.2388 +This leaving variant of the standard, non-leaving descriptor method
1.2389 +differs in that this operation may cause the string descriptor's heap
1.2390 +buffer to be reallocated in order to accommodate the new data. As a
1.2391 +result, MaxLength() and Ptr() may return different values afterwards,
1.2392 +and any existing raw pointers to into the descriptor data may be
1.2393 +invalidated.
1.2394 +
1.2395 +@param aWideCharStr A pointer to a wide character zero terminated string to be copied.
1.2396 +
1.2397 +
1.2398 +@leave KErrNoMemory If the heap buffer of the string descriptor being
1.2399 + assigned to needs to be expanded, but there is
1.2400 + insufficient memory to do so
1.2401 +
1.2402 +@panic USER 11 if aLength is negative.
1.2403 +
1.2404 +@see TDes16::Copy
1.2405 +*/
1.2406 +EXPORT_C void LString16::CopyL(const wchar_t* aWideCharStr)
1.2407 + {
1.2408 + CopyL(reinterpret_cast<const TUint16*>(aWideCharStr));
1.2409 + }
1.2410 +
1.2411 +/**
1.2412 +Appends data onto the end of this descriptor's data and justifies it.
1.2413 +
1.2414 +The source of the appended data is a memory location.
1.2415 +
1.2416 +The target area is considered to be an area of specified width, immediately
1.2417 +following this descriptor's existing data. Source data is copied into, and
1.2418 +aligned within, this target area according to the specified alignment instruction.
1.2419 +
1.2420 +If the length of the target area is larger than the length of the source,
1.2421 +then spare space within the target area is padded with the fill character.
1.2422 +
1.2423 +This leaving variant of the standard, non-leaving descriptor method
1.2424 +differs in that this operation may cause the string descriptor's heap
1.2425 +buffer to be reallocated in order to accommodate the new data. As a
1.2426 +result, MaxLength() and Ptr() may return different values afterwards,
1.2427 +and any existing raw pointers to into the descriptor data may be
1.2428 +invalidated.
1.2429 +
1.2430 +@param aWideCharStr A pointer to a source memory location.
1.2431 +
1.2432 +@param aLength The length of data to be copied. If this is greater than the
1.2433 + width of the target area, then the length of data copied is
1.2434 + limited to the width.
1.2435 +
1.2436 +@param aWidth The width of the target area. If this has the specific negative
1.2437 + value KDefaultJustifyWidth, then the width is
1.2438 + re-set to the length of the data source.
1.2439 +
1.2440 +@param aAlignment The alignment of the data within the target area.
1.2441 +
1.2442 +@param aFill The fill character used to pad the target area.
1.2443 +
1.2444 +@leave KErrNoMemory if the underlying buffer needs to be
1.2445 +grown and there are insufficient resources to do so
1.2446 +
1.2447 +@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
1.2448 +
1.2449 +@panic USER 17 if aLength is negative.
1.2450 +*/
1.2451 +EXPORT_C void LString16::AppendJustifyL(const wchar_t* aWideCharStr,TInt aWidth,TAlign anAlignment,TChar aFill)
1.2452 + {
1.2453 + AppendJustifyL(reinterpret_cast<const TUint16*>( aWideCharStr),aWidth,anAlignment,aFill);
1.2454 + }
1.2455 +
1.2456 +/**
1.2457 +Appends data onto the end of this descriptor's data.
1.2458 +
1.2459 +The length of this descriptor is incremented to reflect the new content.
1.2460 +
1.2461 +This leaving variant of the standard, non-leaving descriptor method
1.2462 +differs in that this operation may cause the string descriptor's heap
1.2463 +buffer to be reallocated in order to accommodate the new data. As a
1.2464 +result, MaxLength() and Ptr() may return different values afterwards,
1.2465 +and any existing raw pointers to into the descriptor data may be
1.2466 +invalidated.
1.2467 +
1.2468 +@param aWideCharStr A pointer to the data to be copied.
1.2469 +@param aLength The length of data to be copied.
1.2470 +
1.2471 +@leave KErrNoMemory if the underlying buffer needs to be
1.2472 +grown and there are insufficient resources to do so
1.2473 +
1.2474 +@panic USER 17 if aLength is negative.
1.2475 +*/
1.2476 +EXPORT_C void LString16::AppendL(const wchar_t* aWideCharStr,TInt aLength)
1.2477 + {
1.2478 + AppendL(reinterpret_cast<const TUint16*>(aWideCharStr),aLength);
1.2479 + }
1.2480 +/**
1.2481 +Appends data onto the end of this descriptor's data.
1.2482 +
1.2483 +The length of this descriptor is incremented to reflect the new content.
1.2484 +
1.2485 +This leaving variant of the standard, non-leaving descriptor method
1.2486 +differs in that this operation may cause the string descriptor's heap
1.2487 +buffer to be reallocated in order to accommodate the new data. As a
1.2488 +result, MaxLength() and Ptr() may return different values afterwards,
1.2489 +and any existing raw pointers to into the descriptor data may be
1.2490 +invalidated.
1.2491 +
1.2492 +@param aWideCharStr A pointer to the data to be copied.
1.2493 +
1.2494 +@leave KErrNoMemory if the underlying buffer needs to be
1.2495 +grown and there are insufficient resources to do so
1.2496 +
1.2497 +@panic USER 17 if aLength is negative.
1.2498 +*/
1.2499 +EXPORT_C void LString16::AppendL(const wchar_t* aWideCharStr)
1.2500 + {
1.2501 + AppendL(reinterpret_cast<const TUint16*>(aWideCharStr));
1.2502 + }
1.2503 +/**
1.2504 +Determines whether this Descriptor's data is equal to the specified
1.2505 +string's data.
1.2506 +
1.2507 +The comparison is implemented internally using the TDesC::Compare() function.
1.2508 +
1.2509 +@param aWideCharStr The wide character string whose data is to be compared
1.2510 + with this Descriptor's data.
1.2511 +
1.2512 +@return True if equal, false otherwise.
1.2513 +
1.2514 +@see TDesC::Compare
1.2515 +*/
1.2516 +EXPORT_C TBool LString16::operator==( const wchar_t* aWideCharStr) const
1.2517 + {
1.2518 + return LString16::operator==(reinterpret_cast<const TUint16*>(aWideCharStr));
1.2519 + }
1.2520 +
1.2521 +/**
1.2522 +Determines whether this Descriptor's data is equal to the specified
1.2523 +string's data.
1.2524 +
1.2525 +The comparison is implemented internally using the TDesC::Compare() function.
1.2526 +
1.2527 +@param aZeroTerminatedString The wide Zero TerminatedString string whose data
1.2528 +is to be compared with this Descriptor's data.
1.2529 +
1.2530 +@return True if equal, false otherwise.
1.2531 +
1.2532 +@see TDesC::Compare
1.2533 +*/
1.2534 +EXPORT_C TBool LString16::operator==( const TUint16* aZeroTerminatedString) const
1.2535 + {
1.2536 + return RBuf16::operator==(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.2537 + }
1.2538 +
1.2539 +/**
1.2540 +Determines whether this descriptor's data is less than the specified
1.2541 +strings's data.
1.2542 +
1.2543 +The comparison is implemented internally using the TDesC::Compare() function.
1.2544 +
1.2545 +@param aWideCharStr The wide character string whose data is to be compared
1.2546 + with this Descriptor's data.
1.2547 +
1.2548 +@return True if this descriptor's data is less than that of the specified string's data
1.2549 +
1.2550 +@see TDesC::Compare
1.2551 +*/
1.2552 +EXPORT_C TBool LString16::operator<( const wchar_t* aWideCharStr) const
1.2553 + {
1.2554 + return LString16::operator<(reinterpret_cast<const TUint16*>(aWideCharStr));
1.2555 + }
1.2556 +
1.2557 +/**
1.2558 +Determines whether this descriptor's data is less than the specified
1.2559 +strings's data.
1.2560 +
1.2561 +The comparison is implemented internally using the TDesC::Compare() function.
1.2562 +
1.2563 +@param aZeroTerminatedString The wide Zero TerminatedString string whose data
1.2564 +is to be compared with this Descriptor's data.
1.2565 +
1.2566 +@return True if this descriptor's data is less than that of the specified string's data
1.2567 +
1.2568 +@see TDesC::Compare
1.2569 +*/
1.2570 +EXPORT_C TBool LString16::operator<(const TUint16* aZeroTerminatedString) const
1.2571 + {
1.2572 + return RBuf16::operator<(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.2573 + }
1.2574 +
1.2575 +/**
1.2576 +Determines whether this descriptor's data is less than the specified
1.2577 +strings's data.
1.2578 +
1.2579 +The comparison is implemented internally using the TDesC::Compare() function.
1.2580 +
1.2581 +@param aWideCharStr The wide character string whose data is to be compared
1.2582 + with this Descriptor's data.
1.2583 +
1.2584 +@return True if this descriptor's data is less than that of the specified string's data
1.2585 +
1.2586 +@see TDesC::Compare
1.2587 +*/
1.2588 +EXPORT_C TBool LString16::operator<=( const wchar_t* aWideCharStr) const
1.2589 + {
1.2590 + return LString16::operator<=(reinterpret_cast<const TUint16*>(aWideCharStr));
1.2591 + }
1.2592 +
1.2593 +/**
1.2594 +Determines whether this descriptor's data is less than/equal to the specified
1.2595 +strings's data.
1.2596 +
1.2597 +The comparison is implemented internally using the TDesC::Compare() function.
1.2598 +
1.2599 +@param aZeroTerminatedString The wide Zero TerminatedString string whose data
1.2600 +is to be compared with this Descriptor's data.
1.2601 +
1.2602 +@return True if this descriptor's data is less than/equal to that of the specified string's data
1.2603 +
1.2604 +@see TDesC::Compare
1.2605 +*/
1.2606 +EXPORT_C TBool LString16::operator<=(const TUint16* aZeroTerminatedString) const
1.2607 + {
1.2608 + return RBuf16::operator<=(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.2609 + }
1.2610 +
1.2611 +/**
1.2612 +Determines whether this descriptor's data is greater than the specified
1.2613 +strings's data.
1.2614 +
1.2615 +The comparison is implemented internally using the TDesC::Compare() function.
1.2616 +
1.2617 +@param aWideCharStr The wide character string whose data is to be compared
1.2618 + with this Descriptor's data.
1.2619 +
1.2620 +@return True if this descriptor's data is greater than that of the specified string's data
1.2621 +
1.2622 +@see TDesC::Compare
1.2623 +*/
1.2624 +EXPORT_C TBool LString16::operator>( const wchar_t* aWideCharStr) const
1.2625 + {
1.2626 + return LString16::operator>(reinterpret_cast<const TUint16*>(aWideCharStr));
1.2627 + }
1.2628 +
1.2629 +/**
1.2630 +Determines whether this descriptor's data is greater than the specified
1.2631 +strings's data.
1.2632 +
1.2633 +The comparison is implemented internally using the TDesC::Compare() function.
1.2634 +
1.2635 +@param aZeroTerminatedString The wide Zero TerminatedString string whose data
1.2636 +is to be compared with this Descriptor's data.
1.2637 +
1.2638 +@return True if this descriptor's data is greater than that of the specified string's data
1.2639 +
1.2640 +@see TDesC::Compare
1.2641 +*/
1.2642 +EXPORT_C TBool LString16::operator>(const TUint16* aZeroTerminatedString) const
1.2643 + {
1.2644 + return RBuf16::operator>(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.2645 + }
1.2646 +
1.2647 +/**
1.2648 +Determines whether this descriptor's data is greater than/equal to the specified
1.2649 +strings's data.
1.2650 +
1.2651 +The comparison is implemented internally using the TDesC::Compare() function.
1.2652 +
1.2653 +@param aWideCharStr The wide character string whose data is to be compared
1.2654 + with this Descriptor's data.
1.2655 +
1.2656 +@return True if this descriptor's data is greater than/equal to that of the specified string's data
1.2657 +
1.2658 +@see TDesC::Compare
1.2659 +*/
1.2660 +EXPORT_C TBool LString16::operator>=( const wchar_t* aWideCharStr) const
1.2661 + {
1.2662 + return LString16::operator>=(reinterpret_cast<const TUint16*>(aWideCharStr));
1.2663 + }
1.2664 +
1.2665 +/**
1.2666 +Determines whether this descriptor's data is greater than the specified
1.2667 +strings's data.
1.2668 +
1.2669 +The comparison is implemented internally using the TDesC::Compare() function.
1.2670 +
1.2671 +@param aZeroTerminatedString The wide Zero TerminatedString string whose data
1.2672 +is to be compared with this Descriptor's data.
1.2673 +
1.2674 +@return True if this descriptor's data is greater than that of the specified string's data
1.2675 +
1.2676 +@see TDesC::Compare
1.2677 +*/
1.2678 +EXPORT_C TBool LString16::operator>=(const TUint16* aZeroTerminatedString) const
1.2679 + {
1.2680 + return RBuf16::operator>=(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.2681 + }
1.2682 +
1.2683 +/**
1.2684 +Determines whether this descriptor's data is not equal to the specified
1.2685 +strings's data.
1.2686 +
1.2687 +The comparison is implemented internally using the TDesC::Compare() function.
1.2688 +
1.2689 +@param aWideCharStr The wide character string whose data is to be compared
1.2690 + with this Descriptor's data.
1.2691 +
1.2692 +@return True if this descriptor's data is not equal to the specified string's data
1.2693 +
1.2694 +@see TDesC::Compare
1.2695 +*/
1.2696 +EXPORT_C TBool LString16::operator!=( const wchar_t* aWideCharStr) const
1.2697 + {
1.2698 + return LString16::operator!=(reinterpret_cast<const TUint16*>(aWideCharStr));
1.2699 + }
1.2700 +
1.2701 +/**
1.2702 +Determines whether this descriptor's data is not equal to the specified
1.2703 +strings's data.
1.2704 +
1.2705 +The comparison is implemented internally using the TDesC::Compare() function.
1.2706 +
1.2707 +@param aZeroTerminatedString The wide Zero TerminatedString string whose data
1.2708 +is to be compared with this Descriptor's data.
1.2709 +
1.2710 +@return True if this descriptor's data is not equal to the specified string's data
1.2711 +
1.2712 +@see TDesC::Compare
1.2713 +*/
1.2714 +EXPORT_C TBool LString16::operator!=(const TUint16* aZeroTerminatedString) const
1.2715 + {
1.2716 + return RBuf16::operator!=(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.2717 + }
1.2718 +
1.2719 +/**
1.2720 +Searches this descriptor's data for a match with the match pattern supplied
1.2721 +in the specified string.
1.2722 +
1.2723 +The match pattern can contain the wildcard characters "*" and "?", where "*"
1.2724 +matches zero or more consecutive occurrences of any character and "?" matches
1.2725 +a single occurrence of any character.
1.2726 +
1.2727 +Note that there is no 'escape character', which means that it is not possible
1.2728 +to match either the "*" character itself or the "?" character itself using
1.2729 +this function.
1.2730 +
1.2731 +@param aWideCharStr The wide character string whose data is to be matched
1.2732 + with this Descriptor's data.
1.2733 +
1.2734 +@return If a match is found, the offset within this descriptor's data where
1.2735 + the match first occurs. KErrNotFound, if there is no match.
1.2736 +*/
1.2737 +EXPORT_C TInt LString16::Match(const wchar_t* aWideCharStr) const
1.2738 + {
1.2739 + return LString16::Match(reinterpret_cast<const TUint16*>(aWideCharStr));
1.2740 + }
1.2741 +
1.2742 +/**
1.2743 +Searches this descriptor's data for a match with the match pattern supplied
1.2744 +in the specified string.
1.2745 +
1.2746 +The match pattern can contain the wildcard characters "*" and "?", where "*"
1.2747 +matches zero or more consecutive occurrences of any character and "?" matches
1.2748 +a single occurrence of any character.
1.2749 +
1.2750 +Note that there is no 'escape character', which means that it is not possible
1.2751 +to match either the "*" character itself or the "?" character itself using
1.2752 +this function.
1.2753 +
1.2754 +@param aZeroTerminatedString The wide Zero TerminatedString string whose data
1.2755 +is to be matched with this Descriptor's data.
1.2756 +
1.2757 +@return If a match is found, the offset within this descriptor's data where
1.2758 + the match first occurs. KErrNotFound, if there is no match.
1.2759 +*/
1.2760 +EXPORT_C TInt LString16::Match(const TUint16* aZeroTerminatedString) const
1.2761 + {
1.2762 + return RBuf16::Match(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.2763 + }
1.2764 +/**
1.2765 +Searches this descriptor's folded data for a match with the folded match
1.2766 +pattern supplied in the specified string.
1.2767 +
1.2768 +The match pattern can contain the wildcard characters "*" and "?", where "*"
1.2769 +matches zero or more consecutive occurrences of any character and "?" matches
1.2770 +a single occurrence of any character.
1.2771 +
1.2772 +Note that folding is locale-independent behaviour. It is also important to
1.2773 +note that there can be no guarantee that folding is in any way culturally
1.2774 +appropriate, and should not be used for matching strings in natural language;
1.2775 +use MatchC() for this.
1.2776 +
1.2777 +Note that there is no 'escape character', which means that it is not possible
1.2778 +to match either the "*" character itself or the "?" character itself using
1.2779 +this function.
1.2780 +
1.2781 +@param aWideCharStr The wide character string whose data is to be matched
1.2782 + with this Descriptor's data.
1.2783 +
1.2784 +@return If a match is found, the offset within this descriptor's data where
1.2785 + the match first occurs. KErrNotFound, if there is no match.
1.2786 +
1.2787 +@see TDesC::MatchC()
1.2788 +*/
1.2789 +EXPORT_C TInt LString16::MatchF(const wchar_t* aWideCharStr) const
1.2790 + {
1.2791 + return LString16::MatchF(reinterpret_cast<const TUint16*>(aWideCharStr));
1.2792 + }
1.2793 +/**
1.2794 +Searches this descriptor's folded data for a match with the folded match
1.2795 +pattern supplied in the specified string.
1.2796 +
1.2797 +The match pattern can contain the wildcard characters "*" and "?", where "*"
1.2798 +matches zero or more consecutive occurrences of any character and "?" matches
1.2799 +a single occurrence of any character.
1.2800 +
1.2801 +Note that folding is locale-independent behaviour. It is also important to
1.2802 +note that there can be no guarantee that folding is in any way culturally
1.2803 +appropriate, and should not be used for matching strings in natural language;
1.2804 +use MatchC() for this.
1.2805 +
1.2806 +Note that there is no 'escape character', which means that it is not possible
1.2807 +to match either the "*" character itself or the "?" character itself using
1.2808 +this function.
1.2809 +
1.2810 +@param aZeroTerminatedString The wide Zero TerminatedString string whose data
1.2811 +is to be matched with this Descriptor's data.
1.2812 +
1.2813 +@return If a match is found, the offset within this descriptor's data where
1.2814 + the match first occurs. KErrNotFound, if there is no match.
1.2815 +
1.2816 +@see TDesC::MatchC()
1.2817 +*/
1.2818 +EXPORT_C TInt LString16::MatchF(const TUint16* aZeroTerminatedString) const
1.2819 + {
1.2820 + return RBuf16::MatchF(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.2821 + }
1.2822 +/**
1.2823 +Compares this descriptor's data with the specified string's data.
1.2824 +
1.2825 +The comparison proceeds on a byte for byte basis. The result of the comparison
1.2826 +is based on the difference of the first bytes to disagree.
1.2827 +
1.2828 +@param aWideCharStr The wide character string whose data is to be compared
1.2829 + with this Descriptor's data.
1.2830 +
1.2831 +@return Positive, if this descriptor is greater than the specified string.
1.2832 + Negative, if this descriptor is less than the specified string.
1.2833 + Zero, if both the descriptor and the string have the same length
1.2834 + and the their contents are the same.
1.2835 +*/
1.2836 +EXPORT_C TInt LString16::Compare(const wchar_t* aWideCharStr) const
1.2837 + {
1.2838 + return LString16::Compare(reinterpret_cast<const TUint16*>(aWideCharStr));
1.2839 + }
1.2840 +
1.2841 +/**
1.2842 +Compares this descriptor's data with the specified string's data.
1.2843 +
1.2844 +The comparison proceeds on a byte for byte basis. The result of the comparison
1.2845 +is based on the difference of the first bytes to disagree.
1.2846 +
1.2847 +@param aZeroTerminatedString The wide Zero TerminatedString string whose data
1.2848 +is to be compared with this Descriptor's data.
1.2849 +
1.2850 +@return Positive, if this descriptor is greater than the specified string.
1.2851 + Negative, if this descriptor is less than the specified string.
1.2852 + Zero, if both the descriptor and the string have the same length
1.2853 + and the their contents are the same.
1.2854 +*/
1.2855 +EXPORT_C TInt LString16::Compare(const TUint16* aZeroTerminatedString) const
1.2856 + {
1.2857 + return RBuf16::Compare(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.2858 + }
1.2859 +/**
1.2860 +Compares this descriptor's folded data with the specified string's folded
1.2861 +data.
1.2862 +
1.2863 +Note that folding is locale-independent behaviour. It is also important to
1.2864 +note that there can be no guarantee that folding is in any way culturally
1.2865 +appropriate, and should not be used for comparing strings in natural language;
1.2866 +
1.2867 +@param aWideCharStr The wide character string whose data is to be compared
1.2868 + with this Descriptor's data.
1.2869 +
1.2870 +@return Positive, if this descriptor is greater than the specified string.
1.2871 + Negative, if this descriptor is less than the specified string.
1.2872 + Zero, if the descriptor and the specified string have the same length
1.2873 + and the their contents are the same.
1.2874 +
1.2875 +@see TDesC::Compare()
1.2876 +*/
1.2877 +EXPORT_C TInt LString16::CompareF(const wchar_t* aWideCharStr) const
1.2878 + {
1.2879 + return LString16::CompareF(reinterpret_cast<const TUint16*>(aWideCharStr));
1.2880 + }
1.2881 +
1.2882 +/**
1.2883 +Compares this descriptor's folded data with the specified string's folded
1.2884 +data.
1.2885 +
1.2886 +Note that folding is locale-independent behaviour. It is also important to
1.2887 +note that there can be no guarantee that folding is in any way culturally
1.2888 +appropriate, and should not be used for comparing strings in natural language;
1.2889 +
1.2890 +@param aZeroTerminatedString The wide Zero Terminated String whose data
1.2891 +is to be compared with this string's data.
1.2892 +
1.2893 +@return Positive, if this descriptor is greater than the specified string.
1.2894 + Negative, if this descriptor is less than the specified string.
1.2895 + Zero, if the descriptor and the specified string have the same length
1.2896 + and the their contents are the same.
1.2897 +
1.2898 +@see TDesC::Compare()
1.2899 +*/
1.2900 +EXPORT_C TInt LString16::CompareF(const TUint16* aZeroTerminatedString) const
1.2901 + {
1.2902 + return RBuf16::CompareF(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.2903 + }
1.2904 +
1.2905 +/**
1.2906 +Searches for the first occurrence of the specified data sequence within this
1.2907 +descriptor.
1.2908 +
1.2909 +Searching always starts at the beginning of this descriptor's data.
1.2910 +
1.2911 +@param aWideCharStr The wide character string whose data is to be searched for,
1.2912 + within this Descriptor's data.
1.2913 +
1.2914 +@return The offset of the data sequence from the beginning of this descriptor's
1.2915 + data. KErrNotFound, if the data sequence cannot be found.
1.2916 +*/
1.2917 +EXPORT_C TInt LString16::Find(const wchar_t* aWideCharStr) const
1.2918 + {
1.2919 + return LString16::Find(reinterpret_cast<const TUint16*>(aWideCharStr));
1.2920 + }
1.2921 +
1.2922 +/**
1.2923 +Searches for the first occurrence of the specified data sequence within this
1.2924 +descriptor.
1.2925 +
1.2926 +Searching always starts at the beginning of this descriptor's data.
1.2927 +
1.2928 +@param aWideCharStr The wide character string whose data is to be searched for,
1.2929 + within this Descriptor's data.
1.2930 +
1.2931 +@return The offset of the data sequence from the beginning of this descriptor's
1.2932 + data. KErrNotFound, if the data sequence cannot be found.
1.2933 +*/
1.2934 +EXPORT_C TInt LString16::Find(const TUint16* aZeroTerminatedString) const
1.2935 + {
1.2936 + return RBuf16::Find(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.2937 + }
1.2938 +
1.2939 +/**
1.2940 +Searches for the first occurrence of the specified data sequence within this
1.2941 +descriptor.
1.2942 +
1.2943 +Searching always starts at the beginning of this descriptor's data.
1.2944 +
1.2945 +@param aWideCharStr The wide character string whose data is to be searched for,
1.2946 + within this Descriptor's data.
1.2947 +@param aLenS The length of the data sequence to be searched for. This value
1.2948 + must not be negative, otherwise the function raises a panic.
1.2949 +
1.2950 +@return The offset of the data sequence from the beginning of this descriptor's
1.2951 + data. KErrNotFound, if the data sequence cannot be found.
1.2952 +
1.2953 +@panic USER 29 if aLenS is negative.
1.2954 +*/
1.2955 +EXPORT_C TInt LString16::Find(const wchar_t* aWideCharStr,TInt aLenS) const
1.2956 + {
1.2957 + return LString16::Find(reinterpret_cast<const TUint16*>(aWideCharStr), aLenS);
1.2958 + }
1.2959 +
1.2960 +/**
1.2961 +Searches for the first occurrence of the specified folded data sequence within
1.2962 +this descriptor's folded data.
1.2963 +
1.2964 +Searching always starts at the beginning of this descriptor's data.
1.2965 +
1.2966 +Note that folding is locale-independent behaviour. It is also important to
1.2967 +note that there can be no guarantee that folding is in any way culturally
1.2968 +appropriate, and should not be used for finding strings in natural language;
1.2969 +
1.2970 +@param aWideCharStr The wide character string whose data is to be searched for,
1.2971 + within this Descriptor's data.
1.2972 +
1.2973 +@return The offset of the data sequence from the beginning of this descriptor's
1.2974 + data. KErrNotFound, if the data sequence cannot be found. Zero, if the
1.2975 + length of the search data sequence is zero.
1.2976 +
1.2977 +*/
1.2978 +EXPORT_C TInt LString16::FindF(const wchar_t* aWideCharStr) const
1.2979 + {
1.2980 + return LString16::FindF(reinterpret_cast<const TUint16*>(aWideCharStr));
1.2981 + }
1.2982 +
1.2983 +/**
1.2984 +Searches for the first occurrence of the specified folded data sequence within
1.2985 +this descriptor's folded data.
1.2986 +
1.2987 +Searching always starts at the beginning of this descriptor's data.
1.2988 +
1.2989 +Note that folding is locale-independent behaviour. It is also important to
1.2990 +note that there can be no guarantee that folding is in any way culturally
1.2991 +appropriate, and should not be used for finding strings in natural language;
1.2992 +
1.2993 +@param aWideCharStr The wide character string whose data is to be searched for,
1.2994 + within this Descriptor's data.
1.2995 +
1.2996 +@return The offset of the data sequence from the beginning of this descriptor's
1.2997 + data. KErrNotFound, if the data sequence cannot be found. Zero, if the
1.2998 + length of the search data sequence is zero.
1.2999 +
1.3000 +*/
1.3001 +EXPORT_C TInt LString16::FindF(const TUint16* aZeroTerminatedString) const
1.3002 + {
1.3003 + return RBuf16::FindF(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.3004 + }
1.3005 +/**
1.3006 +Searches for the first occurrence of the specified folded data sequence within
1.3007 +this descriptor's folded data.
1.3008 +
1.3009 +Searching always starts at the beginning of this descriptor's data.
1.3010 +
1.3011 +Note that folding is locale-independent behaviour. It is also important to
1.3012 +note that there can be no guarantee that folding is in any way culturally
1.3013 +appropriate, and should not be used for finding strings in natural language;
1.3014 +
1.3015 +@param aWideCharStr The wide character string whose data is to be searched for,
1.3016 + within this Descriptor's data.
1.3017 +@param aLenS The length of the data sequence to be searched for. This value
1.3018 + must not be negative, otherwise the function raises a panic.
1.3019 +
1.3020 +@return The offset of the data sequence from the beginning of this descriptor's
1.3021 + data. KErrNotFound, if the data sequence cannot be found. Zero, if the
1.3022 + length of the search data sequence is zero.
1.3023 +
1.3024 +@panic USER 29 if aLenS is negative
1.3025 +
1.3026 +*/
1.3027 +EXPORT_C TInt LString16::FindF(const wchar_t* aWideCharStr, TInt aLen) const
1.3028 + {
1.3029 + return RBuf16::FindF(reinterpret_cast<const TUint16*>(aWideCharStr),aLen);
1.3030 + }
1.3031 +
1.3032 +/**
1.3033 +Copies and folds data from the specified string into this descriptor replacing
1.3034 +any existing data.
1.3035 +
1.3036 +The length of this descriptor is set to reflect the new
1.3037 +data.
1.3038 +
1.3039 +Note that folding is locale-independent behaviour. It is also important to
1.3040 +note that there can be no guarantee that folding is in any way culturally
1.3041 +appropriate, and should not be used when dealing with strings in natural
1.3042 +language.
1.3043 +
1.3044 +This leaving variant of the standard, non-leaving descriptor method
1.3045 +differs in that this operation may cause the string descriptor's heap
1.3046 +buffer to be reallocated in order to accommodate the new data. As a
1.3047 +result, MaxLength() and Ptr() may return different values afterwards,
1.3048 +and any existing raw pointers to into the descriptor data may be
1.3049 +invalidated.
1.3050 +
1.3051 +@param aWideCharStr A wide character string
1.3052 +
1.3053 +@leave KErrNoMemory if the underlying buffer needs to be
1.3054 +grown and there are insufficient resources to do so
1.3055 +*/
1.3056 +EXPORT_C void LString16:: CopyFL(const wchar_t* aWideCharStr )
1.3057 + {
1.3058 + LString16::CopyFL(reinterpret_cast<const TUint16*>(aWideCharStr));
1.3059 + }
1.3060 +
1.3061 +/**
1.3062 +Copies and folds data from the specified string into this descriptor replacing
1.3063 +any existing data.
1.3064 +
1.3065 +The length of this descriptor is set to reflect the new
1.3066 +data.
1.3067 +
1.3068 +Note that folding is locale-independent behaviour. It is also important to
1.3069 +note that there can be no guarantee that folding is in any way culturally
1.3070 +appropriate, and should not be used when dealing with strings in natural
1.3071 +language.
1.3072 +
1.3073 +This leaving variant of the standard, non-leaving descriptor method
1.3074 +differs in that this operation may cause the string descriptor's heap
1.3075 +buffer to be reallocated in order to accommodate the new data. As a
1.3076 +result, MaxLength() and Ptr() may return different values afterwards,
1.3077 +and any existing raw pointers to into the descriptor data may be
1.3078 +invalidated.
1.3079 +
1.3080 +@param aZeroTerminatedString A wide zero terminated string
1.3081 +
1.3082 +@leave KErrNoMemory if the underlying buffer needs to be
1.3083 +grown and there are insufficient resources to do so
1.3084 +*/
1.3085 +EXPORT_C void LString16:: CopyFL(const TUint16* aZeroTerminatedString )
1.3086 + {
1.3087 + LString16::CopyFL(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.3088 + }
1.3089 +
1.3090 +/**
1.3091 +Copies text from the specified string and converts it to lower case before
1.3092 +putting it into this descriptor, replacing any existing data.
1.3093 +
1.3094 +The length of this descriptor is set to reflect the new data.
1.3095 +
1.3096 +Conversion to lower case is implemented as appropriate to the current locale.
1.3097 +
1.3098 +This leaving variant of the standard, non-leaving descriptor method
1.3099 +differs in that this operation may cause the string descriptor's heap
1.3100 +buffer to be reallocated in order to accommodate the new data. As a
1.3101 +result, MaxLength() and Ptr() may return different values afterwards,
1.3102 +and any existing raw pointers to into the descriptor data may be
1.3103 +invalidated.
1.3104 +
1.3105 +@param aWideCharStr A wide character string.
1.3106 +
1.3107 +@leave KErrNoMemory if the underlying buffer needs to be
1.3108 +grown and there are insufficient resources to do so
1.3109 +*/
1.3110 +EXPORT_C void LString16:: CopyLCL(const wchar_t* aWideCharStr)
1.3111 + {
1.3112 + LString16::CopyLCL(reinterpret_cast<const TUint16*>(aWideCharStr));
1.3113 + }
1.3114 +
1.3115 +/**
1.3116 +Copies text from the specified string and converts it to lower case before
1.3117 +putting it into this descriptor, replacing any existing data.
1.3118 +
1.3119 +The length of this descriptor is set to reflect the new data.
1.3120 +
1.3121 +Conversion to lower case is implemented as appropriate to the current locale.
1.3122 +
1.3123 +This leaving variant of the standard, non-leaving descriptor method
1.3124 +differs in that this operation may cause the string descriptor's heap
1.3125 +buffer to be reallocated in order to accommodate the new data. As a
1.3126 +result, MaxLength() and Ptr() may return different values afterwards,
1.3127 +and any existing raw pointers to into the descriptor data may be
1.3128 +invalidated.
1.3129 +
1.3130 +@param aZeroTerminatedString A wide zero terminated string.
1.3131 +
1.3132 +@leave KErrNoMemory if the underlying buffer needs to be
1.3133 +grown and there are insufficient resources to do so
1.3134 +*/
1.3135 +EXPORT_C void LString16:: CopyLCL(const TUint16* aZeroTerminatedString)
1.3136 + {
1.3137 + LString16::CopyLCL(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.3138 + }
1.3139 +
1.3140 +/**
1.3141 +Copies text from the specified string and converts it to upper case before
1.3142 +putting it into this descriptor, replacing any existing data.
1.3143 +
1.3144 +The length of this descriptor is set to reflect the new data.
1.3145 +
1.3146 +Conversion to upper case is implemented as appropriate to the current locale.
1.3147 +
1.3148 +This leaving variant of the standard, non-leaving descriptor method
1.3149 +differs in that this operation may cause the string descriptor's heap
1.3150 +buffer to be reallocated in order to accommodate the new data. As a
1.3151 +result, MaxLength() and Ptr() may return different values afterwards,
1.3152 +and any existing raw pointers to into the descriptor data may be
1.3153 +invalidated.
1.3154 +
1.3155 +@param aWideCharStr A wide character string.
1.3156 +
1.3157 +@leave KErrNoMemory if the underlying buffer needs to be
1.3158 +grown and there are insufficient resources to do so
1.3159 +*/
1.3160 +EXPORT_C void LString16:: CopyUCL(const wchar_t* aWideCharStr)
1.3161 + {
1.3162 + LString16::CopyUCL(reinterpret_cast<const TUint16*>(aWideCharStr));
1.3163 + }
1.3164 +
1.3165 +/**
1.3166 +Copies text from the specified string and converts it to upper case before
1.3167 +putting it into this descriptor, replacing any existing data.
1.3168 +
1.3169 +The length of this descriptor is set to reflect the new data.
1.3170 +
1.3171 +Conversion to upper case is implemented as appropriate to the current locale.
1.3172 +
1.3173 +This leaving variant of the standard, non-leaving descriptor method
1.3174 +differs in that this operation may cause the string descriptor's heap
1.3175 +buffer to be reallocated in order to accommodate the new data. As a
1.3176 +result, MaxLength() and Ptr() may return different values afterwards,
1.3177 +and any existing raw pointers to into the descriptor data may be
1.3178 +invalidated.
1.3179 +
1.3180 +@param aZeroTerminatedString A wide zero terminated string.
1.3181 +
1.3182 +@leave KErrNoMemory if the underlying buffer needs to be
1.3183 +grown and there are insufficient resources to do so
1.3184 +*/
1.3185 +EXPORT_C void LString16:: CopyUCL(const TUint16* aZeroTerminatedString)
1.3186 + {
1.3187 + LString16::CopyUCL(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.3188 + }
1.3189 +
1.3190 +/**
1.3191 +Copies text from the specified string and capitalises it before putting
1.3192 +it into this descriptor, replacing any existing data.
1.3193 +
1.3194 +The length of this descriptor is set to reflect the new data.
1.3195 +
1.3196 +Capitalisation is implemented as appropriate to the current locale.
1.3197 +
1.3198 +This leaving variant of the standard, non-leaving descriptor method
1.3199 +differs in that this operation may cause the string descriptor's heap
1.3200 +buffer to be reallocated in order to accommodate the new data. As a
1.3201 +result, MaxLength() and Ptr() may return different values afterwards,
1.3202 +and any existing raw pointers to into the descriptor data may be
1.3203 +invalidated.
1.3204 +
1.3205 +@param aWideCharStr A wide character string.
1.3206 +
1.3207 +@leave KErrNoMemory if the underlying buffer needs to be
1.3208 +grown and there are insufficient resources to do so
1.3209 +*/
1.3210 +EXPORT_C void LString16:: CopyCPL(const wchar_t* aWideCharStr)
1.3211 + {
1.3212 + LString16::CopyCPL(reinterpret_cast<const TUint16*>(aWideCharStr));
1.3213 + }
1.3214 +
1.3215 +/**
1.3216 +Copies text from the specified string and capitalises it before putting
1.3217 +it into this descriptor, replacing any existing data.
1.3218 +
1.3219 +The length of this descriptor is set to reflect the new data.
1.3220 +
1.3221 +Capitalisation is implemented as appropriate to the current locale.
1.3222 +
1.3223 +This leaving variant of the standard, non-leaving descriptor method
1.3224 +differs in that this operation may cause the string descriptor's heap
1.3225 +buffer to be reallocated in order to accommodate the new data. As a
1.3226 +result, MaxLength() and Ptr() may return different values afterwards,
1.3227 +and any existing raw pointers to into the descriptor data may be
1.3228 +invalidated.
1.3229 +
1.3230 +@param aZeroTerminatedString A wide zero terminated string.
1.3231 +
1.3232 +@leave KErrNoMemory if the underlying buffer needs to be
1.3233 +grown and there are insufficient resources to do so
1.3234 +*/
1.3235 +EXPORT_C void LString16:: CopyCPL(const TUint16* aZeroTerminatedString)
1.3236 + {
1.3237 + LString16::CopyCPL(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.3238 + }
1.3239 +/**
1.3240 +Inserts data into this descriptor.
1.3241 +
1.3242 +The length of this descriptor is changed to reflect the extra data.
1.3243 +
1.3244 +This leaving variant of the standard, non-leaving descriptor method
1.3245 +differs in that this operation may cause the string descriptor's heap
1.3246 +buffer to be reallocated in order to accommodate the new data. As a
1.3247 +result, MaxLength() and Ptr() may return different values afterwards,
1.3248 +and any existing raw pointers to into the descriptor data may be
1.3249 +invalidated.
1.3250 +
1.3251 +@param aPos The position within the data where insertion is to start. This
1.3252 + is an offset value; a zero value refers to the leftmost data
1.3253 + position.
1.3254 +
1.3255 +@param aWideCharStr A wide character string.
1.3256 +
1.3257 +@leave KErrNoMemory if the underlying buffer needs to be
1.3258 +grown and there are insufficient resources to do so
1.3259 +
1.3260 +@panic USER 10 if aPos is negative or is greater than the length of this
1.3261 + descriptor.
1.3262 +*/
1.3263 +EXPORT_C void LString16:: InsertL(TInt aPos,const wchar_t* aWideCharStr)
1.3264 + {
1.3265 + LString16::InsertL(aPos, reinterpret_cast<const TUint16*>(aWideCharStr));
1.3266 + }
1.3267 +
1.3268 +/**
1.3269 +Inserts data into this descriptor.
1.3270 +
1.3271 +The length of this descriptor is changed to reflect the extra data.
1.3272 +
1.3273 +This leaving variant of the standard, non-leaving descriptor method
1.3274 +differs in that this operation may cause the string descriptor's heap
1.3275 +buffer to be reallocated in order to accommodate the new data. As a
1.3276 +result, MaxLength() and Ptr() may return different values afterwards,
1.3277 +and any existing raw pointers to into the descriptor data may be
1.3278 +invalidated.
1.3279 +
1.3280 +@param aPos The position within the data where insertion is to start. This
1.3281 + is an offset value; a zero value refers to the leftmost data
1.3282 + position.
1.3283 +
1.3284 +@param aZeroTerminatedString A wide null terminated string.
1.3285 +
1.3286 +@leave KErrNoMemory if the underlying buffer needs to be
1.3287 +grown and there are insufficient resources to do so
1.3288 +
1.3289 +@panic USER 10 if aPos is negative or is greater than the length of this
1.3290 + descriptor.
1.3291 +*/
1.3292 +EXPORT_C void LString16:: InsertL(TInt aPos,const TUint16* aZeroTerminatedString)
1.3293 + {
1.3294 + LString16::InsertL(aPos,TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.3295 + }
1.3296 +
1.3297 +/**
1.3298 +Replaces data in this descriptor.
1.3299 +
1.3300 +The specified length can be different to the length of the replacement data.
1.3301 +The length of this descriptor changes to reflect the change of data.
1.3302 +
1.3303 +This leaving variant of the standard, non-leaving descriptor method
1.3304 +differs in that this operation may cause the string descriptor's heap
1.3305 +buffer to be reallocated in order to accommodate the new data. As a
1.3306 +result, MaxLength() and Ptr() may return different values afterwards,
1.3307 +and any existing raw pointers to into the descriptor data may be
1.3308 +invalidated.
1.3309 +
1.3310 +@param aPos The position within the data where replacement is to start.
1.3311 + This is an offset value; a zero value refers to the leftmost
1.3312 + data position.
1.3313 +
1.3314 +@param aLength The length of data to be replaced.
1.3315 +
1.3316 +@param aWideCharStr The source wide character string
1.3317 +
1.3318 +@leave KErrNoMemory if the underlying buffer needs to be
1.3319 +grown and there are insufficient resources to do so
1.3320 +
1.3321 +@panic USER 8 if aLength is negative
1.3322 +
1.3323 +@panic USER 10 if aPos is negative or is greater than the length of this
1.3324 + descriptor.
1.3325 +
1.3326 +@panic USER 16 if the length of the source descriptor aDes is negative
1.3327 +*/
1.3328 +EXPORT_C void LString16:: ReplaceL(TInt aPos,TInt aLength,const wchar_t* aWideCharStr)
1.3329 + {
1.3330 + LString16::ReplaceL(aPos,aLength,reinterpret_cast<const TUint16*>(aWideCharStr));
1.3331 + }
1.3332 +
1.3333 +/**
1.3334 +Replaces data in this descriptor.
1.3335 +
1.3336 +The specified length can be different to the length of the replacement data.
1.3337 +The length of this descriptor changes to reflect the change of data.
1.3338 +
1.3339 +This leaving variant of the standard, non-leaving descriptor method
1.3340 +differs in that this operation may cause the string descriptor's heap
1.3341 +buffer to be reallocated in order to accommodate the new data. As a
1.3342 +result, MaxLength() and Ptr() may return different values afterwards,
1.3343 +and any existing raw pointers to into the descriptor data may be
1.3344 +invalidated.
1.3345 +
1.3346 +@param aPos The position within the data where replacement is to start.
1.3347 + This is an offset value; a zero value refers to the leftmost
1.3348 + data position.
1.3349 +
1.3350 +@param aLength The length of data to be replaced.
1.3351 +
1.3352 +@param aZeroTerminatedString The source wide null terminated character string
1.3353 +
1.3354 +@leave KErrNoMemory if the underlying buffer needs to be
1.3355 +grown and there are insufficient resources to do so
1.3356 +
1.3357 +@panic USER 8 if aLength is negative
1.3358 +
1.3359 +@panic USER 10 if aPos is negative or is greater than the length of this
1.3360 + descriptor.
1.3361 +
1.3362 +@panic USER 16 if the length of the source descriptor aDes is negative
1.3363 +*/
1.3364 +EXPORT_C void LString16:: ReplaceL(TInt aPos,TInt aLength,const TUint16* aZeroTerminatedString)
1.3365 + {
1.3366 + LString16::ReplaceL(aPos,aLength,TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.3367 + }
1.3368 +
1.3369 +/**
1.3370 +Copies data into this descriptor and justifies it, replacing any existing data.
1.3371 +
1.3372 +The length of this descriptor is set to reflect the new data.
1.3373 +
1.3374 +The target area is considered to be an area of specified width positioned at
1.3375 +the beginning of this descriptor's data area. Source data is copied into, and
1.3376 +aligned within this target area according to the specified alignment
1.3377 +instruction.
1.3378 +
1.3379 +If the length of the target area is larger than the length of the source, then
1.3380 +spare space within the target area is padded with the fill character.
1.3381 +
1.3382 +This leaving variant of the standard, non-leaving descriptor method
1.3383 +differs in that this operation may cause the string descriptor's heap
1.3384 +buffer to be reallocated in order to accommodate the new data. As a
1.3385 +result, MaxLength() and Ptr() may return different values afterwards,
1.3386 +and any existing raw pointers to into the descriptor data may be
1.3387 +invalidated.
1.3388 +
1.3389 +@param aWideCharStr A wide character string containing the source data.
1.3390 + The length of the data to be copied is the smaller of:
1.3391 + the length of the source descriptor, and
1.3392 + the width of the target area (only if this is not the
1.3393 + explicit negative value KDefaultJustifyWidth).
1.3394 +
1.3395 +@param aWidth The width of the target area. If this has the specific
1.3396 + negative value KDefaultJustifyWidth, then the width is
1.3397 + re-set to the length of the data source.
1.3398 +
1.3399 +@param aAlignment The alignment of the data within the target area
1.3400 +
1.3401 +@param aFill The fill character used to pad the target area.
1.3402 +
1.3403 +@leave KErrNoMemory if the underlying buffer needs to be
1.3404 +grown and there are insufficient resources to do so
1.3405 +
1.3406 +@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
1.3407 +*/
1.3408 +EXPORT_C void LString16:: JustifyL(const wchar_t* aWideCharStr,TInt aWidth,TAlign anAlignment,TChar aFill)
1.3409 + {
1.3410 + LString16::JustifyL(reinterpret_cast<const TUint16*>(aWideCharStr),aWidth,anAlignment,aFill);
1.3411 + }
1.3412 +
1.3413 +/**
1.3414 +Copies data into this descriptor and justifies it, replacing any existing data.
1.3415 +
1.3416 +The length of this descriptor is set to reflect the new data.
1.3417 +
1.3418 +The target area is considered to be an area of specified width positioned at
1.3419 +the beginning of this descriptor's data area. Source data is copied into, and
1.3420 +aligned within this target area according to the specified alignment
1.3421 +instruction.
1.3422 +
1.3423 +If the length of the target area is larger than the length of the source, then
1.3424 +spare space within the target area is padded with the fill character.
1.3425 +
1.3426 +This leaving variant of the standard, non-leaving descriptor method
1.3427 +differs in that this operation may cause the string descriptor's heap
1.3428 +buffer to be reallocated in order to accommodate the new data. As a
1.3429 +result, MaxLength() and Ptr() may return different values afterwards,
1.3430 +and any existing raw pointers to into the descriptor data may be
1.3431 +invalidated.
1.3432 +
1.3433 +@param aWideCharStr A wide character string containing the source data.
1.3434 + The length of the data to be copied is the smaller of:
1.3435 + the length of the source descriptor, and
1.3436 + the width of the target area (only if this is not the
1.3437 + explicit negative value KDefaultJustifyWidth).
1.3438 +
1.3439 +@param aWidth The width of the target area. If this has the specific
1.3440 + negative value KDefaultJustifyWidth, then the width is
1.3441 + re-set to the length of the data source.
1.3442 +
1.3443 +@param aAlignment The alignment of the data within the target area
1.3444 +
1.3445 +@param aFill The fill character used to pad the target area.
1.3446 +
1.3447 +@leave KErrNoMemory if the underlying buffer needs to be
1.3448 +grown and there are insufficient resources to do so
1.3449 +
1.3450 +@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
1.3451 +*/
1.3452 +EXPORT_C void LString16:: JustifyL(const TUint16* aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill)
1.3453 + {
1.3454 + LString16::JustifyL(TPtrC16((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)),aWidth,anAlignment,aFill);
1.3455 + }
1.3456 +
1.3457 +/**
1.3458 +Appends data onto the end of this descriptor's data and justifies it.
1.3459 +
1.3460 +The source of the appended data is a memory location.
1.3461 +
1.3462 +The target area is considered to be an area of specified width, immediately
1.3463 +following this descriptor's existing data. Source data is copied into, and
1.3464 +aligned within, this target area according to the specified alignment instruction.
1.3465 +
1.3466 +If the length of the target area is larger than the length of the source,
1.3467 +then spare space within the target area is padded with the fill character.
1.3468 +
1.3469 +This leaving variant of the standard, non-leaving descriptor method
1.3470 +differs in that this operation may cause the string descriptor's heap
1.3471 +buffer to be reallocated in order to accommodate the new data. As a
1.3472 +result, MaxLength() and Ptr() may return different values afterwards,
1.3473 +and any existing raw pointers to into the descriptor data may be
1.3474 +invalidated.
1.3475 +
1.3476 +@param aString A pointer to a source memory location.
1.3477 +
1.3478 +@param aLength The length of data to be copied. If this is greater than the
1.3479 + width of the target area, then the length of data copied is
1.3480 + limited to the width.
1.3481 +
1.3482 +@param aWidth The width of the target area. If this has the specific negative
1.3483 + value KDefaultJustifyWidth, then the width is
1.3484 + re-set to the length of the data source.
1.3485 +
1.3486 +@param aAlignment The alignment of the data within the target area.
1.3487 +
1.3488 +@param aFill The fill character used to pad the target area.
1.3489 +
1.3490 +@leave KErrNoMemory if the underlying buffer needs to be
1.3491 +grown and there are insufficient resources to do so
1.3492 +
1.3493 +@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
1.3494 +
1.3495 +@panic USER 17 if aLength is negative.
1.3496 +*/
1.3497 +EXPORT_C void LString16:: AppendJustifyL(const wchar_t* aWideCharStr,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill)
1.3498 + {
1.3499 + LString16::AppendJustifyL(reinterpret_cast<const TUint16*>(aWideCharStr),aLength, aWidth,anAlignment,aFill);
1.3500 + }
1.3501 +//eof