1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/ossrv/lowlevellibsandfws/genericusabilitylib/src/lstring8.cpp Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,3501 @@
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 +Aligns the supplied capacity to the nearest growth factor
1.26 +
1.27 +For performance reasons the growth factor, KDefaultExpandSizeShift,
1.28 +is expressed as an exponent of 2 so shifting can be used to achieve the
1.29 +alignment.
1.30 +
1.31 +a KDefaultExpandSizeShift value of 4 is equivalent to 16;
1.32 +giving newCapacity = ((newCapacity / 16) + 1) * 16
1.33 +
1.34 +@param aNewCapacity The size to be aligned
1.35 +
1.36 +@return The new, aligned capacity
1.37 +*/
1.38 +static inline TInt AlignCapacity(TInt aNewCapacity)
1.39 + {
1.40 + const TUint KDefaultExpandSizeShift = 4;
1.41 +
1.42 + return (TInt)((((TUint)aNewCapacity >> KDefaultExpandSizeShift) + 1) << KDefaultExpandSizeShift);
1.43 + }
1.44 +
1.45 +/**
1.46 +Guarantees that MaxLength() is greater than or equal to the supplied
1.47 +capacity, reallocating the supplied capacity if necessary.
1.48 +
1.49 +The actual value of MaxLength() after a call may differ from the exact
1.50 +value requested, but if it does differ it will always be greater. This
1.51 +flexibility allows the implementation to manage heap buffers more
1.52 +efficiently.
1.53 +
1.54 +The string descriptor's heap buffer may be reallocated in order to
1.55 +accommodate the new size. As a
1.56 +result, MaxLength() and Ptr() may return different values afterwards,
1.57 +and any existing raw pointers to into the descriptor data may be
1.58 +invalidated.
1.59 +
1.60 +@param aMinRequiredCapacity The minimum value of MaxLength() required
1.61 +
1.62 +@leave KErrNoMemory if the underlying buffer needs to be
1.63 +grown and there are insufficient resources to do so
1.64 +*/
1.65 +void LString8::ReserveL(TInt aMinRequiredCapacity)
1.66 + {
1.67 + if (MaxLength() < aMinRequiredCapacity)
1.68 + {
1.69 + ReAllocL(AlignCapacity(aMinRequiredCapacity));
1.70 + }
1.71 + }
1.72 +
1.73 +
1.74 +/**
1.75 +Guarantees that MaxLength() is greater than or equal to the supplied
1.76 +integer parameter, growing the underlying heap buffer if necessary.
1.77 +
1.78 +The growth is exponential; maxLength *= 1.5
1.79 +This is reported to give an amortised complexity of O(n) when adding
1.80 +n characters.
1.81 +If the required capacity is larger than the expanded size then the
1.82 +required capacity is used instead.
1.83 +
1.84 +The actual value of MaxLength() after a call may differ from the exact
1.85 +value requested, but if it does differ it will always be greater. This
1.86 +flexibility allows the implementation to manage heap buffers more
1.87 +efficiently.
1.88 +
1.89 +@param aRequiredCapacity The minimum value of MaxLength() required
1.90 +
1.91 +@leave KErrNoMemory if the underlying buffer needs to be
1.92 +grown and there are insufficient resources to do so
1.93 +*/
1.94 +void LString8::ReserveCapacityGrowExponentialL(TInt aRequiredCapacity)
1.95 + {
1.96 + //work in unsigned int for the appropriate shift operation
1.97 + TUint max_length = MaxLength();
1.98 + TUint requiredCapacity = aRequiredCapacity;
1.99 +
1.100 + if (max_length < requiredCapacity)
1.101 + {
1.102 + // max_length *= 3/2;
1.103 + max_length = (max_length + (max_length << 1)) >> 1;
1.104 +
1.105 + // take the bigger of the extended buffer or the required capactiy
1.106 + ReAllocL(AlignCapacity((TInt)(max_length > requiredCapacity ? max_length : requiredCapacity)));
1.107 + }
1.108 + }
1.109 +
1.110 +/**
1.111 +Guarantees that free space in the buffer greater than or equal the
1.112 +supplied integer parameter, growing the underlying heap buffer
1.113 +if necessary.
1.114 +
1.115 +@param aRequiredEmptySpace The minimum value of free space required
1.116 +
1.117 +@leave KErrNoMemory if the underlying buffer needs to be
1.118 +grown and there are insufficient resources to do so
1.119 +*/
1.120 +void LString8::ReserveFreeCapacityGrowExponentialL(TInt aRequiredEmptySpace)
1.121 + {
1.122 + ReserveCapacityGrowExponentialL(Length() + aRequiredEmptySpace);
1.123 + }
1.124 +
1.125 +/**
1.126 +Grows the underlying buffer using the exponential growth
1.127 +function. Guarantees that MaxLength() is greater than or
1.128 +equal to 1.5 * the current MaxLength.
1.129 +
1.130 +
1.131 +@leave KErrNoMemory if the underlying buffer needs to be
1.132 +grown and there are insufficient resources to do so
1.133 +*/
1.134 +void LString8::ReserveCapacityGrowExponentialL()
1.135 + {
1.136 + ReserveCapacityGrowExponentialL(MaxLength() + 1);
1.137 + }
1.138 +
1.139 +
1.140 +/**
1.141 +Default constructor.
1.142 +
1.143 +Constructs a zero-length 8-bit resizable string descriptor.
1.144 +
1.145 +Note that the resulting object owns no allocated memory yet. This
1.146 +default constructor never leaves.
1.147 +*/
1.148 +EXPORT_C LString8::LString8()
1.149 + : iReserved(0)
1.150 + {
1.151 + }
1.152 +
1.153 +/**
1.154 +Destructor.
1.155 +
1.156 +Frees any heap-allocated resources owned by this string descriptor. It
1.157 +is safe to rely on this destructor to perform all necessary cleanup;
1.158 +it is not necessary use the cleanup stack or to call Close() manually.
1.159 +
1.160 +@see RBuf8::Close
1.161 +*/
1.162 +EXPORT_C LString8::~LString8()
1.163 + {
1.164 + RBuf8::Close();
1.165 + }
1.166 +
1.167 +/**
1.168 +Constructor to create a 8-bit resizable string descriptor with an
1.169 +initial capacity.
1.170 +
1.171 +The function allocates sufficient memory to contain descriptor data up to
1.172 +the specified initial maximum length.
1.173 +
1.174 +The current length of the descriptor is set to zero. The maximum length of
1.175 +the descriptor is set to the specified value.
1.176 +
1.177 +@param aMaxLength The maximum length of the descriptor.
1.178 +
1.179 +@leave KErrNoMemory If there is insufficient memory.
1.180 +
1.181 +@see RBuf8::CreateL
1.182 +*/
1.183 +EXPORT_C LString8::LString8(TInt aMaxLength)
1.184 + : iReserved(0)
1.185 + {
1.186 + RBuf8::CreateL(aMaxLength);
1.187 + }
1.188 +
1.189 +/**
1.190 +Constructor to create a 8-bit resizable string descriptor from a
1.191 +pre-allocated heap descriptor.
1.192 +
1.193 +Transfers ownership of the specified heap descriptor to this object.
1.194 +
1.195 +@param aHBuf The heap descriptor to be transferred to this object.
1.196 + This pointer can be NULL, which means that a zero length
1.197 + 8-bit resizable string descriptor is created.
1.198 +
1.199 +@see RBuf8::RBuf8(HBufC8*)
1.200 +*/
1.201 +EXPORT_C LString8::LString8(HBufC8* aHBuf)
1.202 + : iReserved(0)
1.203 + {
1.204 + if (aHBuf)
1.205 + RBuf8::Assign (aHBuf);
1.206 + }
1.207 +
1.208 +/**
1.209 +Constructor to create a 8-bit resizable string descriptor from a
1.210 +pre-allocated raw heap buffer.
1.211 +
1.212 +The allocated memory forms the buffer for this string descriptor. The
1.213 +current length of the descriptor is set to zero.
1.214 +
1.215 +@param aHeapCell The allocated memory to be assigned to this object. This
1.216 + pointer can be NULL, which means that a zero length 8-bit
1.217 + resizable buffer descriptor is created.
1.218 +@param aMaxLength The maximum length of the constructed string descriptor.
1.219 +
1.220 +@panic USER 8 If the specified maximum length is greater then the size of
1.221 + the allocated heap cell, or the specified maximum length
1.222 + is NOT zero when the pointer to the heap cell is NULL.
1.223 +
1.224 +@see RBuf8::Assign()
1.225 +*/
1.226 +EXPORT_C LString8::LString8(TUint8* aHeapCell,TInt aMaxLength)
1.227 + : iReserved(0)
1.228 + {
1.229 + RBuf8::Assign(aHeapCell, aMaxLength);
1.230 + }
1.231 +
1.232 +/**
1.233 +Constructor to create a 8-bit resizable string descriptor from a
1.234 +pre-allocated raw heap buffer.
1.235 +
1.236 +The allocated memory forms the buffer for this string descriptor. The
1.237 +current length of the descriptor is set to the value of the second
1.238 +parameter.
1.239 +
1.240 +@param aHeapCell The allocated memory to be assigned to this object.
1.241 +@param aLength The length of the resulting string descriptor.
1.242 +@param aMaxLength The maximum length of the resulting string descriptor.
1.243 +
1.244 +@panic USER 8 If the specified maximum length is greater then the size of
1.245 + the allocated heap cell, or the specified length is greater then
1.246 + the specified maximum length, or the specified maximum length
1.247 + is NOT zero when the pointer to the heap cell is NULL.
1.248 +
1.249 +@see RBuf8::Assign()
1.250 +*/
1.251 +EXPORT_C LString8::LString8(TUint8* aHeapCell,TInt aLength,TInt aMaxLength)
1.252 + : iReserved(0)
1.253 + {
1.254 + RBuf8::Assign(aHeapCell, aLength, aMaxLength);
1.255 + }
1.256 +
1.257 +/**
1.258 +Constructor to create a 8-bit resizable string descriptor to contain
1.259 +a copy of the specified (source) descriptor, or leave on failure.
1.260 +
1.261 +The constructor allocates sufficient memory so that this string
1.262 +descriptor's maximum length is the same as the length of the source
1.263 +descriptor. Both the current length and the maximum length of this
1.264 +string descriptor are set to the length of the source descriptor.
1.265 +
1.266 +The data contained in the source descriptor is copied into this string
1.267 +descriptor.
1.268 +
1.269 +@param aDes Source descriptor to be copied into this object.
1.270 +
1.271 +@leave KErrNoMemory If there is insufficient memory.
1.272 +
1.273 +@see RBuf8::CreateL()
1.274 +*/
1.275 +EXPORT_C LString8::LString8(const TDesC8& aDes)
1.276 + : iReserved(0)
1.277 + {
1.278 + RBuf8::CreateL(aDes);
1.279 + }
1.280 +
1.281 +/**
1.282 +Copies data into this 8-bit string descriptor, replacing any existing
1.283 +data, and expanding its heap buffer to accommodate if necessary.
1.284 +
1.285 +The length of this descriptor is set to reflect the new data.
1.286 +
1.287 +This operation may cause the target string descriptor's heap buffer to
1.288 +be reallocated in order to accommodate the new data. As a result,
1.289 +MaxLength() and Ptr() may return different values afterwards, and any
1.290 +existing raw pointers to into the descriptor data may be invalidated.
1.291 +
1.292 +Note that the automatic resizing performed is a change to the
1.293 +functionality of this operation compared to other descriptor
1.294 +classes. This change is only active on objects directly declared
1.295 +LString8; when LString8 instances are instead manipulated via
1.296 +references to TDes8 or TDesC8, the standard (non-resizing, panicing)
1.297 +variant is invoked.
1.298 +
1.299 +@param aDes A 8-bit non-modifiable descriptor.
1.300 +
1.301 +@return A reference to this 8-bit string descriptor.
1.302 +
1.303 +@@leave KErrNoMemory If the heap buffer of the string descriptor being
1.304 + assigned to needs to be expanded, but there is
1.305 + insufficient memory to do so
1.306 +
1.307 +@see LString8::CopyL
1.308 +*/
1.309 +EXPORT_C LString8& LString8::operator=(const TDesC8& aDes)
1.310 + {
1.311 + CopyL(aDes);
1.312 + return *this;
1.313 + }
1.314 +
1.315 +
1.316 +/**
1.317 +Transfers ownership of the specified 8-bit descriptor to this object.
1.318 +
1.319 +@param aBuf The source 8-bit buffer. The ownership of this
1.320 + object's buffer is to be transferred.
1.321 +
1.322 +@see Assign()
1.323 +*/
1.324 +EXPORT_C LString8& LString8::operator=(HBufC8* aBuf)
1.325 + {
1.326 + Assign(aBuf);
1.327 + return *this;
1.328 + }
1.329 +
1.330 +
1.331 +/**
1.332 +Copies data into this 8-bit string descriptor, replacing any existing
1.333 +data, and expanding its heap buffer to accommodate if necessary.
1.334 +
1.335 +The length of this descriptor is set to reflect the new data.
1.336 +
1.337 +This leaving variant of the standard, non-leaving descriptor method
1.338 +differs in that this operation may cause the string descriptor's heap
1.339 +buffer to be reallocated in order to accommodate the new data. As a
1.340 +result, MaxLength() and Ptr() may return different values afterwards,
1.341 +and any existing raw pointers to into the descriptor data may be
1.342 +invalidated.
1.343 +
1.344 +@param aDes A 8-bit non-modifiable descriptor.
1.345 +
1.346 +@leave KErrNoMemory If the heap buffer of the string descriptor being
1.347 + assigned to needs to be expanded, but there is
1.348 + insufficient memory to do so
1.349 +
1.350 +@see LString8::operator=
1.351 +@see TDes8::Copy
1.352 +*/
1.353 +EXPORT_C void LString8::CopyL(const TDesC8& aDes)
1.354 + {
1.355 + ReserveL(aDes.Length());
1.356 + RBuf8::Copy(aDes);
1.357 + }
1.358 +
1.359 +/**
1.360 +Copies data into this 8-bit string descriptor, replacing any existing
1.361 +data, and expanding its heap buffer to accommodate if necessary.
1.362 +
1.363 +The length of this descriptor is set to reflect the new data.
1.364 +
1.365 +This leaving variant of the standard, non-leaving descriptor method
1.366 +differs in that this operation may cause the string descriptor's heap
1.367 +buffer to be reallocated in order to accommodate the new data. As a
1.368 +result, MaxLength() and Ptr() may return different values afterwards,
1.369 +and any existing raw pointers to into the descriptor data may be
1.370 +invalidated.
1.371 +
1.372 +@param aDes A 16-bit non-modifiable descriptor.A 16-bit non-modifiable descriptor.
1.373 + Each double-byte value can
1.374 + only be copied into the corresponding single byte when the
1.375 + double-byte value is less than decimal 256. A double-byte value of
1.376 + 256 or greater cannot be copied and the corresponding single byte
1.377 + is set to a value of decimal 1.
1.378 +
1.379 +@leave KErrNoMemory If the heap buffer of the string descriptor being
1.380 + assigned to needs to be expanded, but there is
1.381 + insufficient memory to do so
1.382 +
1.383 +@see TDes8::Copy
1.384 +*/
1.385 +EXPORT_C void LString8::CopyL(const TDesC16& aDes)
1.386 +{
1.387 + ReserveL(aDes.Length());
1.388 + RBuf8::Copy(aDes);
1.389 +}
1.390 +
1.391 +/**
1.392 +Copy constructor to create a 8-bit resizable string descriptor to
1.393 +contain a copy of the specified (source) string descriptor's data, or
1.394 +leave on failure.
1.395 +
1.396 +The constructor allocates sufficient memory so that this string
1.397 +descriptor's maximum length is the same as the length of the source
1.398 +string descriptor. Both the current length and the maximum length of
1.399 +this string descriptor are set to the length of the source descriptor.
1.400 +
1.401 +The data contained in the source string descriptor is copied into this
1.402 +string descriptor.
1.403 +
1.404 +@param aDes Source string descriptor to be copied into this object.
1.405 +
1.406 +@leave KErrNoMemory If there is insufficient memory.
1.407 +
1.408 +@see RBuf8::CreateL()
1.409 +*/
1.410 +EXPORT_C LString8::LString8(const LString8& aDes)
1.411 + : iReserved(0)
1.412 + {
1.413 + RBuf8::CreateL(aDes);
1.414 + }
1.415 +
1.416 +
1.417 +/**
1.418 +Copies data into this 8-bit string descriptor, replacing any existing
1.419 +data, and expanding its heap buffer to accommodate if necessary.
1.420 +
1.421 +The length of this descriptor is set to reflect the new data.
1.422 +
1.423 +This operation may cause the target string descriptor's heap buffer to
1.424 +be reallocated in order to accommodate the new data. As a result,
1.425 +MaxLength() and Ptr() may return different values afterwards, and any
1.426 +existing raw pointers to into the descriptor data may be invalidated.
1.427 +
1.428 +Note that the automatic resizing performed is a change to the
1.429 +functionality of this operation compared to other descriptor
1.430 +classes. This change is only active on objects directly declared
1.431 +LString8; when LString8 instances are instead manipulated via
1.432 +references to TDes8 or TDesC8, the standard (non-resizing, panicing)
1.433 +variant is invoked.
1.434 +
1.435 +@param aDes A 8-bit string descriptor.
1.436 +
1.437 +@return A reference to this 8-bit string descriptor.
1.438 +
1.439 +@leave KErrNoMemory If the heap buffer of the string descriptor being
1.440 + assigned to needs to be expanded, but there is
1.441 + insufficient memory to do so
1.442 +
1.443 +@see LString8::CopyL
1.444 +*/
1.445 +EXPORT_C LString8& LString8::operator=(const LString8& aDes)
1.446 + {
1.447 + CopyL(aDes);
1.448 + return *this;
1.449 + }
1.450 +
1.451 +/**
1.452 +Constructor to create a 8-bit resizable string descriptor containing
1.453 +a copy of the specified (source) zero-terminated string data, or leave
1.454 +on failure.
1.455 +
1.456 +The constructor allocates sufficient memory so that this string
1.457 +descriptor's maximum length is the same as the length of the source
1.458 +string. Both the current length and the maximum length of this string
1.459 +descriptor are set to the length of the source string.
1.460 +
1.461 +The data contained in the source string is copied into this string
1.462 +descriptor. The zero terminator is not copied.
1.463 +
1.464 +@param aZeroTerminatedString A pointer to a zero-terminated string
1.465 +
1.466 +@leave KErrNoMemory If there is insufficient memory.
1.467 +
1.468 +@see LString8::CopyL
1.469 +*/
1.470 +EXPORT_C LString8::LString8(const TUint8* aZeroTerminatedString)
1.471 + : iReserved(0)
1.472 + {
1.473 + CopyL(aZeroTerminatedString);
1.474 + }
1.475 +
1.476 +/**
1.477 +Copies data into this 8-bit string descriptor, replacing any existing
1.478 +data, and expanding its heap buffer to accommodate if necessary.
1.479 +
1.480 +The length of this descriptor is set to reflect the new data.
1.481 +
1.482 +This operation may cause the target string descriptor's heap buffer to
1.483 +be reallocated in order to accommodate the new data. As a result,
1.484 +MaxLength() and Ptr() may return different values afterwards, and any
1.485 +existing raw pointers to into the descriptor data may be invalidated.
1.486 +
1.487 +Note that the automatic resizing performed is a change to the
1.488 +functionality of this operation compared to other descriptor
1.489 +classes. This change is only active on objects directly declared
1.490 +LString8; when LString8 instances are instead manipulated via
1.491 +references to TDes8 or TDesC8, the standard (non-resizing, panicing)
1.492 +variant is invoked.
1.493 +
1.494 +@param aZeroTerminatedString A pointer to a zero-terminated string
1.495 +
1.496 +@return A reference to this 8-bit string descriptor.
1.497 +
1.498 +@leave KErrNoMemory If the heap buffer of the string descriptor being
1.499 + assigned to needs to be expanded, but there is
1.500 + insufficient memory to do so
1.501 +
1.502 +@see LString8::CopyL
1.503 +*/
1.504 +EXPORT_C LString8& LString8::operator=(const TUint8* aZeroTerminatedString)
1.505 + {
1.506 + CopyL(aZeroTerminatedString);
1.507 + return *this;
1.508 + }
1.509 +
1.510 +/**
1.511 +Copies data into this 8-bit string descriptor, replacing any existing
1.512 +data, and expanding its heap buffer to accommodate if necessary.
1.513 +
1.514 +The length of this descriptor is set to reflect the new data.
1.515 +
1.516 +This leaving variant of the standard, non-leaving descriptor method
1.517 +differs in that this operation may cause the string descriptor's heap
1.518 +buffer to be reallocated in order to accommodate the new data. As a
1.519 +result, MaxLength() and Ptr() may return different values afterwards,
1.520 +and any existing raw pointers to into the descriptor data may be
1.521 +invalidated.
1.522 +
1.523 +@param aZeroTerminatedString A pointer to a zero-terminated string
1.524 +
1.525 +@leave KErrNoMemory If the heap buffer of the string descriptor being
1.526 + assigned to needs to be expanded, but there is
1.527 + insufficient memory to do so
1.528 +
1.529 +@see LString8::operator=
1.530 +@see TDes8::Copy
1.531 +*/
1.532 +EXPORT_C void LString8::CopyL(const TUint8* aZeroTerminatedString)
1.533 + {
1.534 + ReserveL(User::StringLength(aZeroTerminatedString));
1.535 + RBuf8::Copy(aZeroTerminatedString);
1.536 + }
1.537 +
1.538 +/**
1.539 +Copies data into this 8-bit string descriptor, replacing any existing
1.540 +data, and expanding its heap buffer to accommodate if necessary.
1.541 +
1.542 +The length of this descriptor is set according to the second
1.543 +parameter.
1.544 +
1.545 +This leaving variant of the standard, non-leaving descriptor method
1.546 +differs in that this operation may cause the string descriptor's heap
1.547 +buffer to be reallocated in order to accommodate the new data. As a
1.548 +result, MaxLength() and Ptr() may return different values afterwards,
1.549 +and any existing raw pointers to into the descriptor data may be
1.550 +invalidated.
1.551 +
1.552 +@param aBuf The start address of data to be copied.
1.553 +@param aLength The length of data to be copied.
1.554 +
1.555 +@leave KErrNoMemory If the heap buffer of the string descriptor being
1.556 + assigned to needs to be expanded, but there is
1.557 + insufficient memory to do so
1.558 +
1.559 +@panic USER 11 if aLength is negative.
1.560 +
1.561 +@see TDes8::Copy
1.562 +*/
1.563 +EXPORT_C void LString8::CopyL(const TUint8* aBuf,TInt aLength)
1.564 + {
1.565 + ReserveL(aLength);
1.566 + RBuf8::Copy(aBuf, aLength);
1.567 + }
1.568 +
1.569 +
1.570 +/**
1.571 +Sets the length of the data represented by the string descriptor to
1.572 +the specified value.
1.573 +
1.574 +This leaving variant of the standard, non-leaving descriptor method
1.575 +differs in that this operation may cause the string descriptor's heap
1.576 +buffer to be reallocated in order to accommodate the new data. As a
1.577 +result, MaxLength() and Ptr() may return different values afterwards,
1.578 +and any existing raw pointers to into the descriptor data may be
1.579 +invalidated.
1.580 +
1.581 +@param aLength The new length of the descriptor.
1.582 +
1.583 +@leave KErrNoMemory if the underlying buffer needs to be
1.584 +grown and there are insufficient resources to do so
1.585 +
1.586 +@panic USER 11 if aLength is negative
1.587 +*/
1.588 +EXPORT_C void LString8::SetLengthL(TInt aLength)
1.589 + {
1.590 + ReserveL(aLength);
1.591 + RBuf8::SetLength(aLength);
1.592 + }
1.593 +
1.594 +
1.595 +/**
1.596 +Sets the storage space allocated to this descriptor to the specified
1.597 +value by growing or compressing its buffer size.
1.598 +
1.599 +If the current length of the descriptor is greater than the specified
1.600 +max length, length is truncated to max length.
1.601 +
1.602 +This leaving variant of the standard, non-leaving descriptor method
1.603 +differs in that this operation may cause the string descriptor's heap
1.604 +buffer to be reallocated in order to accommodate the new data. As a
1.605 +result, MaxLength() and Ptr() may return different values afterwards,
1.606 +and any existing raw pointers to into the descriptor data may be
1.607 +invalidated.
1.608 +
1.609 +@param aMaxLength The new maximum length of the descriptor.
1.610 +
1.611 +@leave KErrNoMemory if the the buffer needs to be
1.612 +reallocated and there are insufficient resources to do so
1.613 +
1.614 +@panic USER 11 if aLength is negative
1.615 +*/
1.616 +EXPORT_C void LString8::SetMaxLengthL(TInt aMaxLength)
1.617 + {
1.618 + if (MaxLength() == aMaxLength)
1.619 + {
1.620 + return;
1.621 + }
1.622 +
1.623 + if (Length() > aMaxLength)
1.624 + {
1.625 + // truncate the current length
1.626 + RBuf8::SetLength(aMaxLength);
1.627 + }
1.628 +
1.629 + ReAllocL(aMaxLength);
1.630 + }
1.631 +
1.632 +
1.633 +/**
1.634 +Ensures that the remaining unused space is more than the supplied value.
1.635 +
1.636 +May reallocate a larger storage space to meet the requirement.
1.637 +As a result MaxLength() and Ptr() may return different values afterwards,
1.638 +and any existing raw pointers to into the descriptor data may be
1.639 +invalidated.
1.640 +
1.641 +Typically, you use this method to reserve a known amount of required space
1.642 +in one go instead of relying on the automatic growth pattern.
1.643 +
1.644 +@param aExtraSpaceLength The extra space required.
1.645 +
1.646 +@leave KErrNoMemory if the the buffer needs to be
1.647 +reallocated and there are insufficient resources to do so.
1.648 +
1.649 +@panic USER 11 if aLength is negative
1.650 +*/
1.651 +EXPORT_C void LString8::ReserveFreeCapacityL(TInt aExtraSpaceLength)
1.652 + {
1.653 + ReserveL(Length() + aExtraSpaceLength);
1.654 + }
1.655 +
1.656 +
1.657 +/**
1.658 +Re-initialises the descriptor destroying its payload
1.659 +
1.660 +*/
1.661 +EXPORT_C void LString8::Reset()
1.662 + {
1.663 + RBuf8::Close();
1.664 + }
1.665 +
1.666 +
1.667 +/**
1.668 +Re-allocates a smaller descriptor buffer space to the current
1.669 +descriptor length
1.670 +
1.671 +This may cause the string descriptor's heap buffer to be reallocated
1.672 +in order to accommodate the new data. As a
1.673 +result, MaxLength() and Ptr() may return different values afterwards,
1.674 +and any existing raw pointers to into the descriptor data may be
1.675 +invalidated.
1.676 +
1.677 +If there is insufficient memory to re-allocate the buffer then the
1.678 +descriptor left unchanged
1.679 +*/
1.680 +EXPORT_C void LString8::Compress()
1.681 + {
1.682 + TInt length = Length();
1.683 + if (MaxLength() > length)
1.684 + {
1.685 + //coverity[checked_return]
1.686 + /*Check for return value from realloc is not needed because neither can
1.687 + * maxlength be negative or length be less than the existing data length
1.688 + */
1.689 + ReAlloc(length);
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 LString8::operator+=
1.712 +*/
1.713 +EXPORT_C void LString8::AppendL(TChar aChar)
1.714 + {
1.715 + ReserveFreeCapacityGrowExponentialL(1);
1.716 + RBuf8::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 LString8::AppendL
1.738 +*/
1.739 +EXPORT_C LString8& LString8::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 8-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 LString8::AppendL(const TDesC8& aDes)
1.763 + {
1.764 + ReserveFreeCapacityGrowExponentialL(aDes.Length());
1.765 + RBuf8::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 8-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 LString8::AppendL
1.786 +*/
1.787 +EXPORT_C LString8& LString8::operator+=(const TDesC8& 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 LString8::AppendL(const TUint8* aBuf,TInt aLength)
1.814 + {
1.815 + ReserveFreeCapacityGrowExponentialL(aLength);
1.816 + RBuf8::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 LString8::FillL(TChar aChar,TInt aLength)
1.843 + {
1.844 + ReserveL(aLength);
1.845 + RBuf8::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 LString8::FillZL(TInt aLength)
1.871 + {
1.872 + ReserveL(aLength);
1.873 + RBuf8::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 LString8::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 LString8::AppendNumFixedWidthL(TUint aVal,TRadix aRadix,TInt aWidth)
1.949 + {
1.950 + ReserveFreeCapacityGrowExponentialL(aWidth);
1.951 + RBuf8::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 TUint8 *LString8::PtrZL()
1.974 + {
1.975 + ReserveFreeCapacityL(1);
1.976 + return RBuf8::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 8-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 LString8::CopyFL(const TDesC8& aDes)
1.1004 + {
1.1005 + ReserveL(aDes.Length());
1.1006 + RBuf8::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 8-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 LString8::CopyCL(const TDesC8& aDes)
1.1028 + {
1.1029 + ReserveL(aDes.Length());
1.1030 + RBuf8::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 8-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 LString8::CopyLCL(const TDesC8& aDes)
1.1054 + {
1.1055 + ReserveL(aDes.Length());
1.1056 + RBuf8::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 8-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 LString8::CopyUCL(const TDesC8& aDes)
1.1080 + {
1.1081 + ReserveL(aDes.Length());
1.1082 + RBuf8::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 8-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 LString8::CopyCPL(const TDesC8& aDes)
1.1106 + {
1.1107 + ReserveL(aDes.Length());
1.1108 + RBuf8::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 LString8::AppendFillL(TChar aChar,TInt aLength)
1.1133 + {
1.1134 + ReserveFreeCapacityGrowExponentialL(aLength);
1.1135 + RBuf8::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 LString8::ZeroTerminateL()
1.1155 + {
1.1156 + ReserveFreeCapacityL(1);
1.1157 + RBuf8::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 LString8, then the function
1.1172 +raises a USER 11 panic. The target LString8 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 8-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 LString8
1.1190 +*/
1.1191 +EXPORT_C void LString8::SwapL(TDes8& aDes)
1.1192 + {
1.1193 + ReserveL(aDes.Length());
1.1194 + TDes8::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 8-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 LString8::SwapL(LString8& aDes)
1.1219 + {
1.1220 + this->ReserveL(aDes.Length());
1.1221 + aDes.ReserveL(this->Length());
1.1222 + TDes8::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 8-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 LString8::InsertL(TInt aPos,const TDesC8& aDes)
1.1251 + {
1.1252 + ReserveFreeCapacityGrowExponentialL(aDes.Length());
1.1253 + RBuf8::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 8-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 LString8::ReplaceL(TInt aPos,TInt aLength,const TDesC8& 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 + RBuf8::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 8-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 LString8::JustifyL(const TDesC8& aDes,TInt aWidth,TAlign aAlignment,TChar aFill)
1.1338 + {
1.1339 + TInt width = (aWidth == KDefaultJustifyWidth ? aDes.Length() : aWidth);
1.1340 + ReserveL(width);
1.1341 + RBuf8::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 TDes8::Format()
1.1383 +*/
1.1384 +EXPORT_C void LString8::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 LString8::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 LString8::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 LString8::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 LString8::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 TDes8::Num()
1.1593 +@see TDes8::NumUC()
1.1594 +*/
1.1595 +EXPORT_C void LString8::FormatL(TRefByValue<const TDesC8> 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 TDes8::Format()
1.1625 +@see VA_LIST
1.1626 +*/
1.1627 +EXPORT_C void LString8::FormatListL(const TDesC8& 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 8-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 LString8::AppendJustifyL(const TDesC8& 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 + RBuf8::AppendJustify(Des, aWidth, aAlignment, aFill);
1.1677 +
1.1678 + }
1.1679 +
1.1680 +/**
1.1681 +Appends data onto the end of this descriptor's data and justifies it.
1.1682 +
1.1683 +The source of the appended data is an existing descriptor.
1.1684 +
1.1685 +The target area is considered to be an area of specified width, immediately
1.1686 +following this descriptor's existing data. Source data is copied into, and
1.1687 +aligned within this target area according to the specified alignment instruction.
1.1688 +
1.1689 +If the length of the target area is larger than the length of the source,
1.1690 +then spare space within the target area is padded with the fill character.
1.1691 +
1.1692 +This leaving variant of the standard, non-leaving descriptor method
1.1693 +differs in that this operation may cause the string descriptor's heap
1.1694 +buffer to be reallocated in order to accommodate the new data. As a
1.1695 +result, MaxLength() and Ptr() may return different values afterwards,
1.1696 +and any existing raw pointers to into the descriptor data may be
1.1697 +invalidated.
1.1698 +
1.1699 +@param aDes An 8-bit non-modifiable descriptor containing the source data.
1.1700 +
1.1701 +@param aLength The length of data to be copied from the source descriptor.
1.1702 + If this is greater than the width of the target area, then
1.1703 + the length of data copied is limited to the width.
1.1704 + The length of data to be copied must not be greater than
1.1705 + the length of the source descriptor. Note that this
1.1706 + condition is not automatically tested.
1.1707 +
1.1708 +@param aWidth The width of the target area. If this has the specific negative
1.1709 + value KDefaultJustifyWidth, then the width is
1.1710 + re-set to the length of the data source.
1.1711 +
1.1712 +@param aAlignment The alignment of the data within the target area.
1.1713 +
1.1714 +@param aFill The fill character used to pad the target area.
1.1715 +
1.1716 +@leave KErrNoMemory if the underlying buffer needs to be
1.1717 +grown and there are insufficient resources to do so
1.1718 +
1.1719 +@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
1.1720 +*/
1.1721 +EXPORT_C void LString8::AppendJustifyL(const TDesC8& Des,TInt aLength,TInt aWidth,TAlign aAlignment,TChar aFill)
1.1722 + {
1.1723 +
1.1724 + TInt width = (aWidth == KDefaultJustifyWidth ? aLength : aWidth);
1.1725 + ReserveFreeCapacityGrowExponentialL(width);
1.1726 +
1.1727 + RBuf8::AppendJustify(Des, aLength, aWidth, aAlignment, aFill);
1.1728 + }
1.1729 +
1.1730 +/**
1.1731 +Appends a zero terminated string onto the end of this descriptor's data and
1.1732 +justifies it.
1.1733 +
1.1734 +The zero terminator is not copied.
1.1735 +
1.1736 +The target area is considered to be an area of specified width, immediately
1.1737 +following this descriptor's existing data. Source data is copied into, and
1.1738 +aligned within, this target area according to the specified alignment instruction.
1.1739 +
1.1740 +If the length of the target area is larger than the length of the source,
1.1741 +then spare space within the target area is padded with the fill character.
1.1742 +
1.1743 +This leaving variant of the standard, non-leaving descriptor method
1.1744 +differs in that this operation may cause the string descriptor's heap
1.1745 +buffer to be reallocated in order to accommodate the new data. As a
1.1746 +result, MaxLength() and Ptr() may return different values afterwards,
1.1747 +and any existing raw pointers to into the descriptor data may be
1.1748 +invalidated.
1.1749 +
1.1750 +@param aZeroTerminatedString A pointer to a zero terminated string The length of the data
1.1751 + to be copied is the smaller of: the length of the string (excluding the zero
1.1752 + terminator), the width of the target area (only if this is not the explicit
1.1753 + negative value KDefaultJustifyWidth).
1.1754 +
1.1755 +@param aWidth The width of the target area. If this has the specific negative
1.1756 + value KDefaultJustifyWidth, then the width is re-set to the length of the
1.1757 + zero terminated string (excluding the zero terminator).
1.1758 +
1.1759 +@param aAlignment The alignment of the data within the target area.
1.1760 +
1.1761 +@param aFill The fill character used to pad the target area.
1.1762 +
1.1763 +@leave KErrNoMemory if the underlying buffer needs to be
1.1764 +grown and there are insufficient resources to do so
1.1765 +
1.1766 +@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
1.1767 +*/
1.1768 +EXPORT_C void LString8::AppendJustifyL(const TUint8* aZeroTerminatedString,TInt aWidth,TAlign aAlignment,TChar aFill)
1.1769 + {
1.1770 +
1.1771 + TInt width = (aWidth == KDefaultJustifyWidth ? User::StringLength(aZeroTerminatedString) : aWidth);
1.1772 + ReserveFreeCapacityGrowExponentialL(width);
1.1773 +
1.1774 + RBuf8::AppendJustify(aZeroTerminatedString, aWidth, aAlignment, aFill);
1.1775 +
1.1776 + }
1.1777 +
1.1778 +/**
1.1779 +Appends data onto the end of this descriptor's data and justifies it.
1.1780 +
1.1781 +The source of the appended data is a memory location.
1.1782 +
1.1783 +The target area is considered to be an area of specified width, immediately
1.1784 +following this descriptor's existing data. Source data is copied into, and
1.1785 +aligned within, this target area according to the specified alignment instruction.
1.1786 +
1.1787 +If the length of the target area is larger than the length of the source,
1.1788 +then spare space within the target area is padded with the fill character.
1.1789 +
1.1790 +This leaving variant of the standard, non-leaving descriptor method
1.1791 +differs in that this operation may cause the string descriptor's heap
1.1792 +buffer to be reallocated in order to accommodate the new data. As a
1.1793 +result, MaxLength() and Ptr() may return different values afterwards,
1.1794 +and any existing raw pointers to into the descriptor data may be
1.1795 +invalidated.
1.1796 +
1.1797 +@param aString A pointer to a source memory location.
1.1798 +
1.1799 +@param aLength The length of data to be copied. If this is greater than the
1.1800 + width of the target area, then the length of data copied is
1.1801 + limited to the width.
1.1802 +
1.1803 +@param aWidth The width of the target area. If this has the specific negative
1.1804 + value KDefaultJustifyWidth, then the width is
1.1805 + re-set to the length of the data source.
1.1806 +
1.1807 +@param aAlignment The alignment of the data within the target area.
1.1808 +
1.1809 +@param aFill The fill character used to pad the target area.
1.1810 +
1.1811 +@leave KErrNoMemory if the underlying buffer needs to be
1.1812 +grown and there are insufficient resources to do so
1.1813 +
1.1814 +@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
1.1815 +
1.1816 +@panic USER 17 if aLength is negative.
1.1817 +*/
1.1818 +EXPORT_C void LString8::AppendJustifyL(const TUint8* aString,TInt aLength,TInt aWidth,TAlign aAlignment,TChar aFill)
1.1819 + {
1.1820 +
1.1821 + TInt width = (aWidth == KDefaultJustifyWidth ? aLength : aWidth);
1.1822 + ReserveFreeCapacityGrowExponentialL(width);
1.1823 +
1.1824 + RBuf8::AppendJustify(aString, aLength, aWidth, aAlignment, aFill);
1.1825 + }
1.1826 +
1.1827 +/**
1.1828 +Converts the specified unsigned integer into a fixed width character
1.1829 +representation based on the specified number system and appends the conversion
1.1830 +onto the end of this descriptor's data.
1.1831 +
1.1832 +The length of this descriptor is incremented to reflect the new content.
1.1833 +
1.1834 +The function generates the exact number of specified characters, either
1.1835 +padding to the left with character zeroes or discarding low order characters
1.1836 +as necessary.
1.1837 +
1.1838 +When a hexadecimal conversion is specified, hexadecimal characters are in
1.1839 +upper case.
1.1840 +
1.1841 +This leaving variant of the standard, non-leaving descriptor method
1.1842 +differs in that this operation may cause the string descriptor's heap
1.1843 +buffer to be reallocated in order to accommodate the new data. As a
1.1844 +result, MaxLength() and Ptr() may return different values afterwards,
1.1845 +and any existing raw pointers to into the descriptor data may be
1.1846 +invalidated.
1.1847 +
1.1848 +@param aVal The unsigned integer value.
1.1849 +@param aRadix The number system representation for the unsigned integer.
1.1850 +@param aWidth The number of characters: to be used to contain the conversion,
1.1851 + to be appended to this descriptor.
1.1852 +
1.1853 +@leave KErrNoMemory if the underlying buffer needs to be
1.1854 +grown and there are insufficient resources to do so
1.1855 +
1.1856 +*/
1.1857 +EXPORT_C void LString8::AppendNumFixedWidthUCL(TUint aVal,TRadix aRadix,TInt aWidth)
1.1858 + {
1.1859 + ReserveFreeCapacityGrowExponentialL(aWidth);
1.1860 + RBuf8::AppendNumFixedWidthUC(aVal, aRadix, aWidth);
1.1861 + }
1.1862 +
1.1863 +/**
1.1864 +Converts the specified 64 bit integer into a character representation
1.1865 +based on the specified number system and appends the conversion onto the end
1.1866 +of this descriptor's data.
1.1867 +
1.1868 +The length of this descriptor is incremented to reflect the new content.
1.1869 +
1.1870 +When a hexadecimal conversion is specified, hexadecimal characters are in
1.1871 +upper case.
1.1872 +
1.1873 +This leaving variant of the standard, non-leaving descriptor method
1.1874 +differs in that this operation may cause the string descriptor's heap
1.1875 +buffer to be reallocated in order to accommodate the new data. As a
1.1876 +result, MaxLength() and Ptr() may return different values afterwards,
1.1877 +and any existing raw pointers to into the descriptor data may be
1.1878 +invalidated.
1.1879 +
1.1880 +@param aVal The 64 bit integer value. This is always treated as an unsigned
1.1881 + value.
1.1882 +@param aRadix The number system representation for the 64 bit integer. If no
1.1883 + explicit value is specified, then EDecimal is the default.
1.1884 +
1.1885 +@leave KErrNoMemory if the underlying buffer needs to be
1.1886 +grown and there are insufficient resources to do so
1.1887 +*/
1.1888 +EXPORT_C void LString8::AppendNumUCL(TUint64 aVal, TRadix aRadix)
1.1889 + {
1.1890 + ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize);
1.1891 + RBuf8::AppendNumUC(aVal, aRadix);
1.1892 + }
1.1893 +
1.1894 +/**
1.1895 +Converts the specified floating point number into a character representation
1.1896 +and appends the conversion onto the end of this descriptor's data.
1.1897 +
1.1898 +The length of this descriptor is incremented to reflect the new content.
1.1899 +
1.1900 +The character representation of the real number is dictated by the specified
1.1901 +format.
1.1902 +
1.1903 +This leaving variant of the standard, non-leaving descriptor method
1.1904 +differs in that this operation may cause the string descriptor's heap
1.1905 +buffer to be reallocated in order to accommodate the new data. As a
1.1906 +result, MaxLength() and Ptr() may return different values afterwards,
1.1907 +and any existing raw pointers to into the descriptor data may be
1.1908 +invalidated.
1.1909 +
1.1910 +@param aVal The floating point number to be converted.
1.1911 +@param aFormat The format of the conversion.
1.1912 +
1.1913 +@return If the conversion is successful, the length of this descriptor. If
1.1914 + the conversion fails, a negative value indicating the cause of failure.
1.1915 + In addition, extra information on the cause of the failure may be
1.1916 + appended onto this descriptor. The possible values and their meaning
1.1917 + are:
1.1918 +
1.1919 + 1.KErrArgument - the supplied floating point number is not a valid
1.1920 + number. The three characters NaN are appended to this descriptor.
1.1921 +
1.1922 + 2.KErrOverflow - the number is too large to represent.
1.1923 + 2.1 For positive overflow, the three characters Inf are appended
1.1924 + to this descriptor.
1.1925 + 2.2 For negative overflow, the four characters -Inf are appended
1.1926 + to this descriptor.
1.1927 +
1.1928 + 3.KErrUnderflow - the number is too small to represent.
1.1929 + 3.1 For positive underflow, the three characters Inf are appended
1.1930 + to this descriptor.
1.1931 + 3.2 For negative underflow, the four characters -Inf are appended
1.1932 + to this descriptor.
1.1933 +
1.1934 + 4.KErrGeneral - the conversion cannot be completed. There are a
1.1935 + number of possible reasons for this, but the most common is:
1.1936 + 4.1 The character representation format (i.e. the format type), as
1.1937 + defined in the TRealFormat object is not recognised.
1.1938 +
1.1939 +@leave KErrNoMemory if the underlying buffer needs to be
1.1940 +grown and there are insufficient resources to do so
1.1941 +*/
1.1942 +EXPORT_C TInt LString8::AppendNumL(TReal aVal,const TRealFormat& aFormat)
1.1943 + {
1.1944 + ReserveFreeCapacityGrowExponentialL(aFormat.iWidth + 1 + KDefaultExpandSize);
1.1945 + return RBuf8::AppendNum(aVal, aFormat);
1.1946 + }
1.1947 +
1.1948 +/**
1.1949 +Converts the 64-bit signed integer into a decimal character representation
1.1950 +and appends the conversion onto the end of this descriptor's data.
1.1951 +
1.1952 +The length of this descriptor is incremented to reflect the new content.
1.1953 +
1.1954 +If the integer is negative, the character representation is prefixed by a
1.1955 +minus sign.
1.1956 +
1.1957 +This leaving variant of the standard, non-leaving descriptor method
1.1958 +differs in that this operation may cause the string descriptor's heap
1.1959 +buffer to be reallocated in order to accommodate the new data. As a
1.1960 +result, MaxLength() and Ptr() may return different values afterwards,
1.1961 +and any existing raw pointers to into the descriptor data may be
1.1962 +invalidated.
1.1963 +
1.1964 +@param aVal The 64-bit signed integer value.
1.1965 +
1.1966 +@leave KErrNoMemory if the underlying buffer needs to be
1.1967 +grown and there are insufficient resources to do so
1.1968 +*/
1.1969 +EXPORT_C void LString8::AppendNumL(TInt64 aVal)
1.1970 + {
1.1971 + ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize);
1.1972 + RBuf8::AppendNum(aVal);
1.1973 + }
1.1974 +
1.1975 +/**
1.1976 +Converts the specified 64 bit integer into a character representation
1.1977 +based on the specified number system and appends the conversion onto the end
1.1978 +of this descriptor's data.
1.1979 +
1.1980 +The length of this descriptor is incremented to reflect the new content.
1.1981 +
1.1982 +When a hexadecimal conversion is specified, hexadecimal characters are in
1.1983 +lower case.
1.1984 +
1.1985 +This leaving variant of the standard, non-leaving descriptor method
1.1986 +differs in that this operation may cause the string descriptor's heap
1.1987 +buffer to be reallocated in order to accommodate the new data. As a
1.1988 +result, MaxLength() and Ptr() may return different values afterwards,
1.1989 +and any existing raw pointers to into the descriptor data may be
1.1990 +invalidated.
1.1991 +
1.1992 +@param aVal The 64 bit integer value. This is always treated as an unsigned
1.1993 + value.
1.1994 +@param aRadix The number system representation for the 64 bit integer.
1.1995 +
1.1996 +@leave KErrNoMemory if the underlying buffer needs to be
1.1997 +grown and there are insufficient resources to do so
1.1998 +*/
1.1999 +EXPORT_C void LString8::AppendNumL(TUint64 aVal, TRadix aRadix)
1.2000 + {
1.2001 + ReserveFreeCapacityGrowExponentialL(64 + 1 + KDefaultExpandSize);
1.2002 + RBuf8::AppendNum(aVal, aRadix);
1.2003 + }
1.2004 +
1.2005 +/**
1.2006 +Formats and appends text onto the end of this descriptor's data.
1.2007 +
1.2008 +The length of this descriptor is incremented to reflect the new content.
1.2009 +
1.2010 +The function takes a format string and a variable number of arguments.
1.2011 +The format string contains literal text, embedded with directives,
1.2012 +for converting the trailing list of arguments into text.
1.2013 +
1.2014 +The embedded directives are character sequences prefixed with the '%' character.
1.2015 +The literal text is simply copied into this descriptor unaltered while
1.2016 +the '%' directives are used to convert successive arguments from the
1.2017 +trailing list. See the description of the Format() function.
1.2018 +
1.2019 +Literal text is appended on a character by character basis, and the
1.2020 +underlying buffer is grown as necessary to accommodate it.
1.2021 +
1.2022 +Text converted from a trailing argument is appended as a complete
1.2023 +string, and the underlying buffer is grown as necessary to accommodate
1.2024 +it.
1.2025 +
1.2026 +This leaving variant of the standard, non-leaving descriptor method
1.2027 +differs in that this operation may cause the string descriptor's heap
1.2028 +buffer to be reallocated in order to accommodate the new data. As a
1.2029 +result, MaxLength() and Ptr() may return different values afterwards,
1.2030 +and any existing raw pointers to into the descriptor data may be
1.2031 +invalidated.
1.2032 +
1.2033 +@param aFmt The 8-bit non-modifiable descriptor containing the
1.2034 + format string. The TRefByValue class provides a
1.2035 + constructor which takes a TDesC8 type.
1.2036 +
1.2037 +@param ... A variable number of arguments to be converted to text
1.2038 + as dictated by the format string.
1.2039 +
1.2040 +@leave KErrNoMemory if the underlying buffer needs to be
1.2041 +grown and there are insufficient resources to do so
1.2042 +
1.2043 +@panic USER 12 if the format string has incorrect syntax.
1.2044 +
1.2045 +@see TDes8::Format()
1.2046 +@see TDes8Overflow::Overflow()
1.2047 +*/
1.2048 +EXPORT_C void LString8::AppendFormatL(TRefByValue<const TDesC8> aFmt,...)
1.2049 + {
1.2050 + VA_LIST list;
1.2051 + VA_START(list,aFmt);
1.2052 + AppendFormatListL(aFmt,list);
1.2053 + }
1.2054 +
1.2055 +class TRetryOverflow8 : public TDes8Overflow
1.2056 + {
1.2057 +public:
1.2058 + TRetryOverflow8() : iOverflow(EFalse)
1.2059 + {
1.2060 + }
1.2061 +
1.2062 + virtual void Overflow(TDes8& /*aDes*/)
1.2063 + {
1.2064 + iOverflow = ETrue;
1.2065 + }
1.2066 +
1.2067 + TBool iOverflow;
1.2068 + };
1.2069 +
1.2070 +/**
1.2071 +Formats and appends text onto the end of this descriptor's data.
1.2072 +
1.2073 +The length of this descriptor is incremented to reflect the new content.
1.2074 +
1.2075 +The behaviour of this function is the same as
1.2076 +AppendFormatL(TRefByValue<const TDesC8> aFmt,TDes8Overflow *aOverflowHandler,...).
1.2077 +In practice, it is better and easier to use AppendFormat(), passing a variable number of
1.2078 +arguments as required by the format string.
1.2079 +
1.2080 +This leaving variant of the standard, non-leaving descriptor method
1.2081 +differs in that this operation may cause the string descriptor's heap
1.2082 +buffer to be reallocated in order to accommodate the new data. As a
1.2083 +result, MaxLength() and Ptr() may return different values afterwards,
1.2084 +and any existing raw pointers to into the descriptor data may be
1.2085 +invalidated.
1.2086 +
1.2087 +@param aFmt The descriptor containing the format string.
1.2088 +@param aList A pointer to an argument list.
1.2089 +
1.2090 +@leave KErrNoMemory if the underlying buffer needs to be
1.2091 +grown and there are insufficient resources to do so
1.2092 +
1.2093 +@see TDes8::AppendFormat
1.2094 +@see VA_LIST
1.2095 +*/
1.2096 +EXPORT_C void LString8::AppendFormatListL(const TDesC8& aFmt,VA_LIST aList)
1.2097 + {
1.2098 + ReserveFreeCapacityGrowExponentialL(aFmt.Length() + KDefaultExpandSize); // We use aFmt as a hint
1.2099 + for (;;)
1.2100 + {
1.2101 + TInt before = Length();
1.2102 + TRetryOverflow8 overflow;
1.2103 + RBuf8::AppendFormatList(aFmt, aList, &overflow);
1.2104 + if (overflow.iOverflow)
1.2105 + {
1.2106 + SetLengthL(before); // Can't leave
1.2107 + ReserveCapacityGrowExponentialL();
1.2108 + }
1.2109 + else
1.2110 + {
1.2111 + break;
1.2112 + }
1.2113 + }
1.2114 + }
1.2115 +
1.2116 +
1.2117 +/**
1.2118 +Unlinks and transfers ownership of the specified 8-bit resizable descriptor's
1.2119 +buffer to this object. The source descriptor is detached from the buffer.
1.2120 +
1.2121 +@param aString The source 8-bit resizable buffer. The ownership of this
1.2122 + object's buffer is to be transferred.
1.2123 +
1.2124 +*/
1.2125 +EXPORT_C void LString8::Assign(const LString8& aString)
1.2126 + {
1.2127 + // free any previously owned resource
1.2128 + Reset();
1.2129 +
1.2130 + RBuf8::Assign(aString);
1.2131 + // unlink buffer from original descriptor
1.2132 + new (const_cast<LString8*>(&aString)) LString8();
1.2133 + }
1.2134 +
1.2135 +
1.2136 +/**
1.2137 +Transfers ownership of the specified 8-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 8-bit resizable buffer. The ownership of this
1.2141 + object's buffer is to be transferred.
1.2142 +
1.2143 +@see RBuf8::Assign()
1.2144 +*/
1.2145 +
1.2146 +EXPORT_C void LString8::Assign(const RBuf8& aRBuf)
1.2147 + {
1.2148 + // free any previously owned resource
1.2149 + Reset();
1.2150 +
1.2151 + RBuf8::Assign(aRBuf);
1.2152 +
1.2153 + // reset the RBuf;
1.2154 + new (const_cast<RBuf8*>(&aRBuf)) RBuf8();
1.2155 + }
1.2156 +
1.2157 +
1.2158 +/**
1.2159 +Transfers ownership of the specified 8-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 RBuf8::Assign()
1.2165 +*/
1.2166 +EXPORT_C void LString8::Assign(HBufC8* aHBuf)
1.2167 + {
1.2168 + // free any previously owned resource
1.2169 + Reset();
1.2170 +
1.2171 + RBuf8::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 + 8-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 RBuf8::Assign()
1.2189 +*/
1.2190 +EXPORT_C void LString8::Assign(TUint8 *aHeapCell, TInt aMaxLength)
1.2191 + {
1.2192 + // free any previously owned resource
1.2193 + Reset();
1.2194 +
1.2195 + RBuf8::Assign(aHeapCell, aMaxLength);
1.2196 + }
1.2197 +
1.2198 +
1.2199 +/**
1.2200 +Transfers ownership of the specified 16-bit resizable descriptor's this object.
1.2201 +
1.2202 +@param aHeapCell The allocated memory to be assigned to this object.
1.2203 +
1.2204 +@param aLength The length of the descriptor.
1.2205 +
1.2206 +@param aMaxLength The maximum length of the descriptor.
1.2207 +
1.2208 +@panic USER 8 If the specified maximum length is greater then the size of the
1.2209 + allocated heap cell, or the specified length is greater then
1.2210 + the specified maximum length, or the specified maximum length
1.2211 + is NOT zero when the pointer to the heap cell is NULL.
1.2212 +
1.2213 +@see RBuf8::Assign()
1.2214 +*/
1.2215 +EXPORT_C void LString8::Assign(TUint8* aHeapCell,TInt aLength,TInt aMaxLength)
1.2216 + {
1.2217 + // free any previously owned resource
1.2218 + Reset();
1.2219 +
1.2220 + RBuf8::Assign(aHeapCell, aLength, aMaxLength);
1.2221 + }
1.2222 +
1.2223 +/**
1.2224 +Creates an 8-bit resizable buffer descriptor that has been initialised with
1.2225 +data from the specified read stream; leaves on failure.
1.2226 +
1.2227 +Data is assigned to the new descriptor from the specified stream.
1.2228 +This variant assumes that the stream contains the length of the data followed
1.2229 +by the data itself.
1.2230 +
1.2231 +The function is implemented by calling the HBufC8::NewL(RReadStream&,TInt)
1.2232 +variant and then assigning the resulting heap descriptor using
1.2233 +the RBuf8::Assign(HBufC8*) variant. The comments that describe
1.2234 +the HBufC8::NewL() variant also apply to this RBuf8::CreateL() function.
1.2235 +
1.2236 +The function may leave with one of the system-wide error codes, specifically
1.2237 +KErrOverflow, if the length of the data as read from the stream is greater than
1.2238 +the upper limit as specified by the aMaxLength parameter.
1.2239 +
1.2240 +@param aStream The stream from which the data length and the data to be
1.2241 + assigned to the new descriptor, are taken.
1.2242 +@param aMaxLength The upper limit on the length of data that the descriptor is
1.2243 + to represent. The value of this parameter must be non-negative
1.2244 + otherwise the underlying function will panic.
1.2245 +*/
1.2246 +EXPORT_C void LString8::CreateL(RReadStream &aStream,TInt aMaxLength)
1.2247 + {
1.2248 + Reset();
1.2249 + Assign(HBufC8::NewL(aStream,aMaxLength));
1.2250 + }
1.2251 +
1.2252 +/**
1.2253 +Appends data onto the end of this descriptor's data.
1.2254 +
1.2255 +The length of this descriptor is incremented to reflect the new content.
1.2256 +
1.2257 +This leaving variant of the standard, non-leaving descriptor method
1.2258 +differs in that this operation may cause the string descriptor's heap
1.2259 +buffer to be reallocated in order to accommodate the new data. As a
1.2260 +result, MaxLength() and Ptr() may return different values afterwards,
1.2261 +and any existing raw pointers to into the descriptor data may be
1.2262 +invalidated.
1.2263 +
1.2264 +@param aZeroTerminatedString A pointer to a zero terminated string .
1.2265 +@leave KErrNoMemory if the underlying buffer needs to be
1.2266 +grown and there are insufficient resources to do so
1.2267 +
1.2268 +@see LString8::AppendL
1.2269 +*/
1.2270 +EXPORT_C LString8& LString8::operator+=(const TUint8* aZeroTerminatedString)
1.2271 + {
1.2272 + AppendL(aZeroTerminatedString,User::StringLength(aZeroTerminatedString));
1.2273 + return *this;
1.2274 + }
1.2275 +/**
1.2276 +Appends data onto the end of this descriptor's data.
1.2277 +
1.2278 +The length of this descriptor is incremented to reflect the new content.
1.2279 +
1.2280 +This leaving variant of the standard, non-leaving descriptor method
1.2281 +differs in that this operation may cause the string descriptor's heap
1.2282 +buffer to be reallocated in order to accommodate the new data. As a
1.2283 +result, MaxLength() and Ptr() may return different values afterwards,
1.2284 +and any existing raw pointers to into the descriptor data may be
1.2285 +invalidated.
1.2286 +
1.2287 +@param aZeroTerminatedString A pointer to the data to be copied.
1.2288 +
1.2289 +@leave KErrNoMemory if the underlying buffer needs to be
1.2290 +grown and there are insufficient resources to do so
1.2291 +
1.2292 +@panic USER 17 if aLength is negative.
1.2293 +*/
1.2294 +EXPORT_C void LString8::AppendL(const TUint8* aZeroTerminatedString)
1.2295 + {
1.2296 + AppendL(aZeroTerminatedString,User::StringLength(aZeroTerminatedString));
1.2297 + }
1.2298 +/**
1.2299 +Constructor to create a 8-bit resizable string descriptor containing
1.2300 +a copy of the specified (source) zero-terminated character string data, or leave
1.2301 +on failure.
1.2302 +
1.2303 +The constructor allocates sufficient memory so that this string
1.2304 +descriptor's maximum length is the same as the length of the source
1.2305 +string. Both the current length and the maximum length of this string
1.2306 +descriptor are set to the length of the source string.
1.2307 +
1.2308 +The data contained in the source string is copied into this string
1.2309 +descriptor. The zero terminator is not copied.
1.2310 +
1.2311 +@param aCharStr A pointer to a zero-terminated wide character string
1.2312 +
1.2313 +@leave KErrNoMemory If there is insufficient memory.
1.2314 +
1.2315 +@see LString8::CopyL
1.2316 +*/
1.2317 +EXPORT_C LString8::LString8(const char* aCharStr)
1.2318 + : iReserved(0)
1.2319 + {
1.2320 + CopyL(reinterpret_cast<const TUint8*>(aCharStr));
1.2321 + }
1.2322 +
1.2323 +/**
1.2324 +Copies data into this 8-bit string descriptor, replacing any existing
1.2325 +data, and expanding its heap buffer to accommodate if necessary.
1.2326 +
1.2327 +The length of this descriptor is set to reflect the new data.
1.2328 +
1.2329 +This operation may cause the target string descriptor's heap buffer to
1.2330 +be reallocated in order to accommodate the new data. As a result,
1.2331 +MaxLength() and Ptr() may return different values afterwards, and any
1.2332 +existing raw pointers to into the descriptor data may be invalidated.
1.2333 +
1.2334 +Note that the automatic resizing performed is a change to the
1.2335 +functionality of this operation compared to other descriptor
1.2336 +classes. This change is only active on objects directly declared
1.2337 +LString8; when LString8 instances are instead manipulated via
1.2338 +references to TDes8 or TDesC8, the standard (non-resizing, panicing)
1.2339 +variant is invoked.
1.2340 +
1.2341 +@param aCharStr A pointer to a character zero-terminated string
1.2342 +
1.2343 +@return A reference to this 8-bit string descriptor.
1.2344 +
1.2345 +@leave KErrNoMemory If the heap buffer of the string descriptor being
1.2346 + assigned to needs to be expanded, but there is
1.2347 + insufficient memory to do so
1.2348 +
1.2349 +@see LString8::CopyL
1.2350 +*/
1.2351 +EXPORT_C LString8& LString8::operator=(const char* aCharStr)
1.2352 + {
1.2353 + CopyL(reinterpret_cast<const TUint8*>(aCharStr));
1.2354 + return *this;
1.2355 + }
1.2356 +
1.2357 +/**
1.2358 +Appends data onto the end of this descriptor's data.
1.2359 +
1.2360 +The length of this descriptor is incremented to reflect the new content.
1.2361 +
1.2362 +This leaving variant of the standard, non-leaving descriptor method
1.2363 +differs in that this operation may cause the string descriptor's heap
1.2364 +buffer to be reallocated in order to accommodate the new data. As a
1.2365 +result, MaxLength() and Ptr() may return different values afterwards,
1.2366 +and any existing raw pointers to into the descriptor data may be
1.2367 +invalidated.
1.2368 +
1.2369 +@param aCharStr A pointer to a character zero terminated string .
1.2370 +@leave KErrNoMemory if the underlying buffer needs to be
1.2371 +grown and there are insufficient resources to do so
1.2372 +
1.2373 +@see LString8::AppendL
1.2374 +*/
1.2375 +EXPORT_C LString8& LString8::operator+=(const char* aCharStr)
1.2376 + {
1.2377 + AppendL(reinterpret_cast<const TUint8*>(aCharStr),User::StringLength(reinterpret_cast<const TUint8*>(aCharStr)));
1.2378 + return *this;
1.2379 + }
1.2380 +
1.2381 +/**
1.2382 +Copies data into this 8-bit string descriptor, replacing any existing
1.2383 +data, and expanding its heap buffer to accommodate if necessary.
1.2384 +
1.2385 +The length of this descriptor is set according to the new
1.2386 +parameter.
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 aCharStr A pointer to a 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 TDes8::Copy
1.2405 +*/
1.2406 +EXPORT_C void LString8::CopyL(const char* aCharStr)
1.2407 + {
1.2408 + CopyL(reinterpret_cast<const TUint8*>(aCharStr));
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 aCharStr 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 LString8::AppendJustifyL(const char* aCharStr,TInt aWidth,TAlign anAlignment,TChar aFill)
1.2452 + {
1.2453 + AppendJustifyL(reinterpret_cast<const TUint8*>( aCharStr),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 aCharStr 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 LString8::AppendL(const char* aCharStr,TInt aLength)
1.2477 + {
1.2478 + AppendL(reinterpret_cast<const TUint8*>(aCharStr),aLength);
1.2479 + }
1.2480 +
1.2481 +/**
1.2482 +Appends data onto the end of this descriptor's data.
1.2483 +
1.2484 +The length of this descriptor is incremented to reflect the new content.
1.2485 +
1.2486 +This leaving variant of the standard, non-leaving descriptor method
1.2487 +differs in that this operation may cause the string descriptor's heap
1.2488 +buffer to be reallocated in order to accommodate the new data. As a
1.2489 +result, MaxLength() and Ptr() may return different values afterwards,
1.2490 +and any existing raw pointers to into the descriptor data may be
1.2491 +invalidated.
1.2492 +
1.2493 +@param aCharStr A pointer to the data to be copied.
1.2494 +
1.2495 +@leave KErrNoMemory if the underlying buffer needs to be
1.2496 +grown and there are insufficient resources to do so
1.2497 +
1.2498 +@panic USER 17 if aLength is negative.
1.2499 +*/
1.2500 +EXPORT_C void LString8::AppendL(const char* aCharStr)
1.2501 + {
1.2502 + AppendL(reinterpret_cast<const TUint8*>(aCharStr));
1.2503 + }
1.2504 +
1.2505 +/**
1.2506 +Determines whether this Descriptor's data is equal to the specified
1.2507 +string's data.
1.2508 +
1.2509 +The comparison is implemented internally using the TDesC8::Compare() function.
1.2510 +
1.2511 +@param aCharStr The 8-bit character string whose data is to be compared
1.2512 + with this Descriptor's data.
1.2513 +
1.2514 +@return True if equal, false otherwise.
1.2515 +
1.2516 +@see TDesC8::Compare
1.2517 +*/
1.2518 +EXPORT_C TBool LString8::operator==( const char* aCharStr) const
1.2519 + {
1.2520 + return LString8::operator==(reinterpret_cast<const TUint8*>(aCharStr));
1.2521 + }
1.2522 +
1.2523 +/**
1.2524 +Determines whether this Descriptor's data is equal to the specified
1.2525 +string's data.
1.2526 +
1.2527 +The comparison is implemented internally using the TDesC8::Compare() function.
1.2528 +
1.2529 +@param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data
1.2530 +is to be compared with this Descriptor's data.
1.2531 +
1.2532 +@return True if equal, false otherwise.
1.2533 +
1.2534 +@see TDesC8::Compare
1.2535 +*/
1.2536 +EXPORT_C TBool LString8::operator==( const TUint8* aZeroTerminatedString) const
1.2537 + {
1.2538 + return RBuf8::operator==(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.2539 + }
1.2540 +
1.2541 +/**
1.2542 +Determines whether this descriptor's data is less than the specified
1.2543 +strings's data.
1.2544 +
1.2545 +The comparison is implemented internally using the TDesC8::Compare() function.
1.2546 +
1.2547 +@param aCharStr The 8-bit character string whose data is to be compared
1.2548 + with this Descriptor's data.
1.2549 +
1.2550 +@return True if this descriptor's data is less than that of the specified string's data
1.2551 +
1.2552 +@see TDesC8::Compare
1.2553 +*/
1.2554 +EXPORT_C TBool LString8::operator<( const char* aCharStr) const
1.2555 + {
1.2556 + return LString8::operator<(reinterpret_cast<const TUint8*>(aCharStr));
1.2557 + }
1.2558 +
1.2559 +/**
1.2560 +Determines whether this descriptor's data is less than the specified
1.2561 +strings's data.
1.2562 +
1.2563 +The comparison is implemented internally using the TDesC8::Compare() function.
1.2564 +
1.2565 +@param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data
1.2566 +is to be compared with this Descriptor's data.
1.2567 +
1.2568 +@return True if this descriptor's data is less than that of the specified string's data
1.2569 +
1.2570 +@see TDesC8::Compare
1.2571 +*/
1.2572 +EXPORT_C TBool LString8::operator<(const TUint8* aZeroTerminatedString) const
1.2573 + {
1.2574 + return RBuf8::operator<(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.2575 + }
1.2576 +
1.2577 +/**
1.2578 +Determines whether this descriptor's data is less than the specified
1.2579 +strings's data.
1.2580 +
1.2581 +The comparison is implemented internally using the TDesC8::Compare() function.
1.2582 +
1.2583 +@param aCharStr The 8-bit character string whose data is to be compared
1.2584 + with this Descriptor's data.
1.2585 +
1.2586 +@return True if this descriptor's data is less than that of the specified string's data
1.2587 +
1.2588 +@see TDesC8::Compare
1.2589 +*/
1.2590 +EXPORT_C TBool LString8::operator<=( const char* aCharStr) const
1.2591 + {
1.2592 + return LString8::operator<=(reinterpret_cast<const TUint8*>(aCharStr));
1.2593 + }
1.2594 +
1.2595 +/**
1.2596 +Determines whether this descriptor's data is less than/equal to the specified
1.2597 +strings's data.
1.2598 +
1.2599 +The comparison is implemented internally using the TDesC8::Compare() function.
1.2600 +
1.2601 +@param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data
1.2602 +is to be compared with this Descriptor's data.
1.2603 +
1.2604 +@return True if this descriptor's data is less than/equal to that of the specified string's data
1.2605 +
1.2606 +@see TDesC8::Compare
1.2607 +*/
1.2608 +EXPORT_C TBool LString8::operator<=(const TUint8* aZeroTerminatedString) const
1.2609 + {
1.2610 + return RBuf8::operator<=(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.2611 + }
1.2612 +
1.2613 +/**
1.2614 +Determines whether this descriptor's data is greater than the specified
1.2615 +strings's data.
1.2616 +
1.2617 +The comparison is implemented internally using the TDesC8::Compare() function.
1.2618 +
1.2619 +@param aCharStr The 8-bit character string whose data is to be compared
1.2620 + with this Descriptor's data.
1.2621 +
1.2622 +@return True if this descriptor's data is greater than that of the specified string's data
1.2623 +
1.2624 +@see TDesC8::Compare
1.2625 +*/
1.2626 +EXPORT_C TBool LString8::operator>( const char* aCharStr) const
1.2627 + {
1.2628 + return LString8::operator>(reinterpret_cast<const TUint8*>(aCharStr));
1.2629 + }
1.2630 +
1.2631 +/**
1.2632 +Determines whether this descriptor's data is greater than the specified
1.2633 +strings's data.
1.2634 +
1.2635 +The comparison is implemented internally using the TDesC8::Compare() function.
1.2636 +
1.2637 +@param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data
1.2638 +is to be compared with this Descriptor's data.
1.2639 +
1.2640 +@return True if this descriptor's data is greater than that of the specified string's data
1.2641 +
1.2642 +@see TDesC8::Compare
1.2643 +*/
1.2644 +EXPORT_C TBool LString8::operator>(const TUint8* aZeroTerminatedString) const
1.2645 + {
1.2646 + return RBuf8::operator>(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.2647 + }
1.2648 +
1.2649 +/**
1.2650 +Determines whether this descriptor's data is greater than/equal to the specified
1.2651 +strings's data.
1.2652 +
1.2653 +The comparison is implemented internally using the TDesC8::Compare() function.
1.2654 +
1.2655 +@param aCharStr The 8-bit character string whose data is to be compared
1.2656 + with this Descriptor's data.
1.2657 +
1.2658 +@return True if this descriptor's data is greater than/equal to that of the specified string's data
1.2659 +
1.2660 +@see TDesC8::Compare
1.2661 +*/
1.2662 +EXPORT_C TBool LString8::operator>=( const char* aCharStr) const
1.2663 + {
1.2664 + return LString8::operator>=(reinterpret_cast<const TUint8*>(aCharStr));
1.2665 + }
1.2666 +
1.2667 +/**
1.2668 +Determines whether this descriptor's data is greater than the specified
1.2669 +strings's data.
1.2670 +
1.2671 +The comparison is implemented internally using the TDesC8::Compare() function.
1.2672 +
1.2673 +@param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data
1.2674 +is to be compared with this Descriptor's data.
1.2675 +
1.2676 +@return True if this descriptor's data is greater than that of the specified string's data
1.2677 +
1.2678 +@see TDesC8::Compare
1.2679 +*/
1.2680 +EXPORT_C TBool LString8::operator>=(const TUint8* aZeroTerminatedString) const
1.2681 + {
1.2682 + return RBuf8::operator>=(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.2683 + }
1.2684 +
1.2685 +/**
1.2686 +Determines whether this descriptor's data is not equal to the specified
1.2687 +strings's data.
1.2688 +
1.2689 +The comparison is implemented internally using the TDesC8::Compare() function.
1.2690 +
1.2691 +@param aCharStr The 8-bit character string whose data is to be compared
1.2692 + with this Descriptor's data.
1.2693 +
1.2694 +@return True if this descriptor's data is not equal to the specified string's data
1.2695 +
1.2696 +@see TDesC8::Compare
1.2697 +*/
1.2698 +EXPORT_C TBool LString8::operator!=( const char* aCharStr) const
1.2699 + {
1.2700 + return LString8::operator!=(reinterpret_cast<const TUint8*>(aCharStr));
1.2701 + }
1.2702 +
1.2703 +/**
1.2704 +Determines whether this descriptor's data is not equal to the specified
1.2705 +strings's data.
1.2706 +
1.2707 +The comparison is implemented internally using the TDesC8::Compare() function.
1.2708 +
1.2709 +@param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data
1.2710 +is to be compared with this Descriptor's data.
1.2711 +
1.2712 +@return True if this descriptor's data is not equal to the specified string's data
1.2713 +
1.2714 +@see TDesC8::Compare
1.2715 +*/
1.2716 +EXPORT_C TBool LString8::operator!=(const TUint8* aZeroTerminatedString) const
1.2717 + {
1.2718 + return RBuf8::operator!=(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.2719 + }
1.2720 +
1.2721 +/**
1.2722 +Searches this descriptor's data for a match with the match pattern supplied
1.2723 +in the specified string.
1.2724 +
1.2725 +The match pattern can contain the wildcard characters "*" and "?", where "*"
1.2726 +matches zero or more consecutive occurrences of any character and "?" matches
1.2727 +a single occurrence of any character.
1.2728 +
1.2729 +Note that there is no 'escape character', which means that it is not possible
1.2730 +to match either the "*" character itself or the "?" character itself using
1.2731 +this function.
1.2732 +
1.2733 +@param aCharStr The 8-bit character string whose data is to be matched
1.2734 + with this Descriptor's data.
1.2735 +
1.2736 +@return If a match is found, the offset within this descriptor's data where
1.2737 + the match first occurs. KErrNotFound, if there is no match.
1.2738 +*/
1.2739 +EXPORT_C TInt LString8::Match(const char* aCharStr) const
1.2740 + {
1.2741 + return LString8::Match(reinterpret_cast<const TUint8*>(aCharStr));
1.2742 + }
1.2743 +
1.2744 +/**
1.2745 +Searches this descriptor's data for a match with the match pattern supplied
1.2746 +in the specified string.
1.2747 +
1.2748 +The match pattern can contain the wildcard characters "*" and "?", where "*"
1.2749 +matches zero or more consecutive occurrences of any character and "?" matches
1.2750 +a single occurrence of any character.
1.2751 +
1.2752 +Note that there is no 'escape character', which means that it is not possible
1.2753 +to match either the "*" character itself or the "?" character itself using
1.2754 +this function.
1.2755 +
1.2756 +@param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data
1.2757 +is to be matched with this Descriptor's data.
1.2758 +
1.2759 +@return If a match is found, the offset within this descriptor's data where
1.2760 + the match first occurs. KErrNotFound, if there is no match.
1.2761 +*/
1.2762 +EXPORT_C TInt LString8::Match(const TUint8* aZeroTerminatedString) const
1.2763 + {
1.2764 + return RBuf8::Match(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.2765 + }
1.2766 +/**
1.2767 +Searches this descriptor's folded data for a match with the folded match
1.2768 +pattern supplied in the specified string.
1.2769 +
1.2770 +The match pattern can contain the wildcard characters "*" and "?", where "*"
1.2771 +matches zero or more consecutive occurrences of any character and "?" matches
1.2772 +a single occurrence of any character.
1.2773 +
1.2774 +Note that folding is locale-independent behaviour. It is also important to
1.2775 +note that there can be no guarantee that folding is in any way culturally
1.2776 +appropriate, and should not be used for matching strings in natural language;
1.2777 +use MatchC() for this.
1.2778 +
1.2779 +Note that there is no 'escape character', which means that it is not possible
1.2780 +to match either the "*" character itself or the "?" character itself using
1.2781 +this function.
1.2782 +
1.2783 +@param aCharStr The 8-bit character string whose data is to be matched
1.2784 + with this Descriptor's data.
1.2785 +
1.2786 +@return If a match is found, the offset within this descriptor's data where
1.2787 + the match first occurs. KErrNotFound, if there is no match.
1.2788 +
1.2789 +@see TDesC8::MatchC()
1.2790 +*/
1.2791 +EXPORT_C TInt LString8::MatchF(const char* aCharStr) const
1.2792 + {
1.2793 + return LString8::MatchF(reinterpret_cast<const TUint8*>(aCharStr));
1.2794 + }
1.2795 +/**
1.2796 +Searches this descriptor's folded data for a match with the folded match
1.2797 +pattern supplied in the specified string.
1.2798 +
1.2799 +The match pattern can contain the wildcard characters "*" and "?", where "*"
1.2800 +matches zero or more consecutive occurrences of any character and "?" matches
1.2801 +a single occurrence of any character.
1.2802 +
1.2803 +Note that folding is locale-independent behaviour. It is also important to
1.2804 +note that there can be no guarantee that folding is in any way culturally
1.2805 +appropriate, and should not be used for matching strings in natural language;
1.2806 +use MatchC() for this.
1.2807 +
1.2808 +Note that there is no 'escape character', which means that it is not possible
1.2809 +to match either the "*" character itself or the "?" character itself using
1.2810 +this function.
1.2811 +
1.2812 +@param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data
1.2813 +is to be matched with this Descriptor's data.
1.2814 +
1.2815 +@return If a match is found, the offset within this descriptor's data where
1.2816 + the match first occurs. KErrNotFound, if there is no match.
1.2817 +
1.2818 +@see TDesC8::MatchC()
1.2819 +*/
1.2820 +EXPORT_C TInt LString8::MatchF(const TUint8* aZeroTerminatedString) const
1.2821 + {
1.2822 + return RBuf8::MatchF(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.2823 + }
1.2824 +/**
1.2825 +Compares this descriptor's data with the specified string's data.
1.2826 +
1.2827 +The comparison proceeds on a byte for byte basis. The result of the comparison
1.2828 +is based on the difference of the first bytes to disagree.
1.2829 +
1.2830 +@param aCharStr The 8-bit character string whose data is to be compared
1.2831 + with this Descriptor's data.
1.2832 +
1.2833 +@return Positive, if this descriptor is greater than the specified string.
1.2834 + Negative, if this descriptor is less than the specified string.
1.2835 + Zero, if both the descriptor and the string have the same length
1.2836 + and the their contents are the same.
1.2837 +*/
1.2838 +EXPORT_C TInt LString8::Compare(const char* aCharStr) const
1.2839 + {
1.2840 + return LString8::Compare(reinterpret_cast<const TUint8*>(aCharStr));
1.2841 + }
1.2842 +
1.2843 +/**
1.2844 +Compares this descriptor's data with the specified string's data.
1.2845 +
1.2846 +The comparison proceeds on a byte for byte basis. The result of the comparison
1.2847 +is based on the difference of the first bytes to disagree.
1.2848 +
1.2849 +@param aZeroTerminatedString The 8-bit Zero TerminatedString string whose data
1.2850 +is to be compared with this Descriptor's data.
1.2851 +
1.2852 +@return Positive, if this descriptor is greater than the specified string.
1.2853 + Negative, if this descriptor is less than the specified string.
1.2854 + Zero, if both the descriptor and the string have the same length
1.2855 + and the their contents are the same.
1.2856 +*/
1.2857 +EXPORT_C TInt LString8::Compare(const TUint8* aZeroTerminatedString) const
1.2858 + {
1.2859 + return RBuf8::Compare(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.2860 + }
1.2861 +/**
1.2862 +Compares this descriptor's folded data with the specified string's folded
1.2863 +data.
1.2864 +
1.2865 +Note that folding is locale-independent behaviour. It is also important to
1.2866 +note that there can be no guarantee that folding is in any way culturally
1.2867 +appropriate, and should not be used for comparing strings in natural language;
1.2868 +
1.2869 +@param aCharStr The 8-bit character string whose data is to be compared
1.2870 + with this Descriptor's data.
1.2871 +
1.2872 +@return Positive, if this descriptor is greater than the specified string.
1.2873 + Negative, if this descriptor is less than the specified string.
1.2874 + Zero, if the descriptor and the specified string have the same length
1.2875 + and the their contents are the same.
1.2876 +
1.2877 +@see TDesC8::Compare()
1.2878 +*/
1.2879 +EXPORT_C TInt LString8::CompareF(const char* aCharStr) const
1.2880 + {
1.2881 + return LString8::CompareF(reinterpret_cast<const TUint8*>(aCharStr));
1.2882 + }
1.2883 +
1.2884 +/**
1.2885 +Compares this descriptor's folded data with the specified string's folded
1.2886 +data.
1.2887 +
1.2888 +Note that folding is locale-independent behaviour. It is also important to
1.2889 +note that there can be no guarantee that folding is in any way culturally
1.2890 +appropriate, and should not be used for comparing strings in natural language;
1.2891 +
1.2892 +@param aZeroTerminatedString The 8-bit Zero Terminated String whose data
1.2893 +is to be compared with this string's data.
1.2894 +
1.2895 +@return Positive, if this descriptor is greater than the specified string.
1.2896 + Negative, if this descriptor is less than the specified string.
1.2897 + Zero, if the descriptor and the specified string have the same length
1.2898 + and the their contents are the same.
1.2899 +
1.2900 +@see TDesC8::Compare()
1.2901 +*/
1.2902 +EXPORT_C TInt LString8::CompareF(const TUint8* aZeroTerminatedString) const
1.2903 + {
1.2904 + return RBuf8::CompareF(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.2905 + }
1.2906 +
1.2907 +/**
1.2908 +Searches for the first occurrence of the specified data sequence within this
1.2909 +descriptor.
1.2910 +
1.2911 +Searching always starts at the beginning of this descriptor's data.
1.2912 +
1.2913 +@param aCharStr The 8-bit character string whose data is to be searched for,
1.2914 + within this Descriptor's data.
1.2915 +
1.2916 +@return The offset of the data sequence from the beginning of this descriptor's
1.2917 + data. KErrNotFound, if the data sequence cannot be found.
1.2918 +*/
1.2919 +EXPORT_C TInt LString8::Find(const char* aCharStr) const
1.2920 + {
1.2921 + return LString8::Find(reinterpret_cast<const TUint8*>(aCharStr));
1.2922 + }
1.2923 +
1.2924 +/**
1.2925 +Searches for the first occurrence of the specified data sequence within this
1.2926 +descriptor.
1.2927 +
1.2928 +Searching always starts at the beginning of this descriptor's data.
1.2929 +
1.2930 +@param aCharStr The 8-bit character string whose data is to be searched for,
1.2931 + within this Descriptor's data.
1.2932 +
1.2933 +@return The offset of the data sequence from the beginning of this descriptor's
1.2934 + data. KErrNotFound, if the data sequence cannot be found.
1.2935 +*/
1.2936 +EXPORT_C TInt LString8::Find(const TUint8* aZeroTerminatedString) const
1.2937 + {
1.2938 + return RBuf8::Find(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.2939 + }
1.2940 +
1.2941 +/**
1.2942 +Searches for the first occurrence of the specified data sequence within this
1.2943 +descriptor.
1.2944 +
1.2945 +Searching always starts at the beginning of this descriptor's data.
1.2946 +
1.2947 +@param aCharStr The 8-bit character string whose data is to be searched for,
1.2948 + within this Descriptor's data.
1.2949 +@param aLenS The length of the data sequence to be searched for. This value
1.2950 + must not be negative, otherwise the function raises a panic.
1.2951 +
1.2952 +@return The offset of the data sequence from the beginning of this descriptor's
1.2953 + data. KErrNotFound, if the data sequence cannot be found.
1.2954 +
1.2955 +@panic USER 29 if aLenS is negative.
1.2956 +*/
1.2957 +EXPORT_C TInt LString8::Find(const char* aCharStr,TInt aLenS) const
1.2958 + {
1.2959 + return LString8::Find(reinterpret_cast<const TUint8*>(aCharStr), aLenS);
1.2960 + }
1.2961 +
1.2962 +/**
1.2963 +Searches for the first occurrence of the specified folded data sequence within
1.2964 +this descriptor's folded data.
1.2965 +
1.2966 +Searching always starts at the beginning of this descriptor's data.
1.2967 +
1.2968 +Note that folding is locale-independent behaviour. It is also important to
1.2969 +note that there can be no guarantee that folding is in any way culturally
1.2970 +appropriate, and should not be used for finding strings in natural language;
1.2971 +
1.2972 +@param aCharStr The 8-bit character string whose data is to be searched for,
1.2973 + within this Descriptor's data.
1.2974 +
1.2975 +@return The offset of the data sequence from the beginning of this descriptor's
1.2976 + data. KErrNotFound, if the data sequence cannot be found. Zero, if the
1.2977 + length of the search data sequence is zero.
1.2978 +
1.2979 +*/
1.2980 +EXPORT_C TInt LString8::FindF(const char* aCharStr) const
1.2981 + {
1.2982 + return LString8::FindF(reinterpret_cast<const TUint8*>(aCharStr));
1.2983 + }
1.2984 +
1.2985 +/**
1.2986 +Searches for the first occurrence of the specified folded data sequence within
1.2987 +this descriptor's folded data.
1.2988 +
1.2989 +Searching always starts at the beginning of this descriptor's data.
1.2990 +
1.2991 +Note that folding is locale-independent behaviour. It is also important to
1.2992 +note that there can be no guarantee that folding is in any way culturally
1.2993 +appropriate, and should not be used for finding strings in natural language;
1.2994 +
1.2995 +@param aCharStr The 8-bit character string whose data is to be searched for,
1.2996 + within this Descriptor's data.
1.2997 +
1.2998 +@return The offset of the data sequence from the beginning of this descriptor's
1.2999 + data. KErrNotFound, if the data sequence cannot be found. Zero, if the
1.3000 + length of the search data sequence is zero.
1.3001 +
1.3002 +*/
1.3003 +EXPORT_C TInt LString8::FindF(const TUint8* aZeroTerminatedString) const
1.3004 + {
1.3005 + return RBuf8::FindF(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.3006 + }
1.3007 +/**
1.3008 +Searches for the first occurrence of the specified folded data sequence within
1.3009 +this descriptor's folded data.
1.3010 +
1.3011 +Searching always starts at the beginning of this descriptor's data.
1.3012 +
1.3013 +Note that folding is locale-independent behaviour. It is also important to
1.3014 +note that there can be no guarantee that folding is in any way culturally
1.3015 +appropriate, and should not be used for finding strings in natural language;
1.3016 +
1.3017 +@param aCharStr The 8-bit character string whose data is to be searched for,
1.3018 + within this Descriptor's data.
1.3019 +@param aLenS The length of the data sequence to be searched for. This value
1.3020 + must not be negative, otherwise the function raises a panic.
1.3021 +
1.3022 +@return The offset of the data sequence from the beginning of this descriptor's
1.3023 + data. KErrNotFound, if the data sequence cannot be found. Zero, if the
1.3024 + length of the search data sequence is zero.
1.3025 +
1.3026 +@panic USER 29 if aLenS is negative
1.3027 +
1.3028 +*/
1.3029 +EXPORT_C TInt LString8::FindF(const char* aCharStr, TInt aLen) const
1.3030 + {
1.3031 + return RBuf8::FindF(reinterpret_cast<const TUint8*>(aCharStr),aLen);
1.3032 + }
1.3033 +
1.3034 +/**
1.3035 +Copies and folds data from the specified string into this descriptor replacing
1.3036 +any existing data.
1.3037 +
1.3038 +The length of this descriptor is set to reflect the new
1.3039 +data.
1.3040 +
1.3041 +Note that folding is locale-independent behaviour. It is also important to
1.3042 +note that there can be no guarantee that folding is in any way culturally
1.3043 +appropriate, and should not be used when dealing with strings in natural
1.3044 +language.
1.3045 +
1.3046 +This leaving variant of the standard, non-leaving descriptor method
1.3047 +differs in that this operation may cause the string descriptor's heap
1.3048 +buffer to be reallocated in order to accommodate the new data. As a
1.3049 +result, MaxLength() and Ptr() may return different values afterwards,
1.3050 +and any existing raw pointers to into the descriptor data may be
1.3051 +invalidated.
1.3052 +
1.3053 +@param aCharStr A 8-bit character string
1.3054 +
1.3055 +@leave KErrNoMemory if the underlying buffer needs to be
1.3056 +grown and there are insufficient resources to do so
1.3057 +*/
1.3058 +EXPORT_C void LString8:: CopyFL(const char* aCharStr )
1.3059 + {
1.3060 + LString8::CopyFL(reinterpret_cast<const TUint8*>(aCharStr));
1.3061 + }
1.3062 +
1.3063 +/**
1.3064 +Copies and folds data from the specified string into this descriptor replacing
1.3065 +any existing data.
1.3066 +
1.3067 +The length of this descriptor is set to reflect the new
1.3068 +data.
1.3069 +
1.3070 +Note that folding is locale-independent behaviour. It is also important to
1.3071 +note that there can be no guarantee that folding is in any way culturally
1.3072 +appropriate, and should not be used when dealing with strings in natural
1.3073 +language.
1.3074 +
1.3075 +This leaving variant of the standard, non-leaving descriptor method
1.3076 +differs in that this operation may cause the string descriptor's heap
1.3077 +buffer to be reallocated in order to accommodate the new data. As a
1.3078 +result, MaxLength() and Ptr() may return different values afterwards,
1.3079 +and any existing raw pointers to into the descriptor data may be
1.3080 +invalidated.
1.3081 +
1.3082 +@param aZeroTerminatedString A 8-bit zero terminated string
1.3083 +
1.3084 +@leave KErrNoMemory if the underlying buffer needs to be
1.3085 +grown and there are insufficient resources to do so
1.3086 +*/
1.3087 +EXPORT_C void LString8:: CopyFL(const TUint8* aZeroTerminatedString )
1.3088 + {
1.3089 + LString8::CopyFL(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.3090 + }
1.3091 +
1.3092 +/**
1.3093 +Copies text from the specified string and converts it to lower case before
1.3094 +putting it into this descriptor, replacing any existing data.
1.3095 +
1.3096 +The length of this descriptor is set to reflect the new data.
1.3097 +
1.3098 +Conversion to lower case is implemented as appropriate to the current locale.
1.3099 +
1.3100 +This leaving variant of the standard, non-leaving descriptor method
1.3101 +differs in that this operation may cause the string descriptor's heap
1.3102 +buffer to be reallocated in order to accommodate the new data. As a
1.3103 +result, MaxLength() and Ptr() may return different values afterwards,
1.3104 +and any existing raw pointers to into the descriptor data may be
1.3105 +invalidated.
1.3106 +
1.3107 +@param aCharStr A 8-bit character string.
1.3108 +
1.3109 +@leave KErrNoMemory if the underlying buffer needs to be
1.3110 +grown and there are insufficient resources to do so
1.3111 +*/
1.3112 +EXPORT_C void LString8:: CopyLCL(const char* aCharStr)
1.3113 + {
1.3114 + LString8::CopyLCL(reinterpret_cast<const TUint8*>(aCharStr));
1.3115 + }
1.3116 +
1.3117 +/**
1.3118 +Copies text from the specified string and converts it to lower case before
1.3119 +putting it into this descriptor, replacing any existing data.
1.3120 +
1.3121 +The length of this descriptor is set to reflect the new data.
1.3122 +
1.3123 +Conversion to lower case is implemented as appropriate to the current locale.
1.3124 +
1.3125 +This leaving variant of the standard, non-leaving descriptor method
1.3126 +differs in that this operation may cause the string descriptor's heap
1.3127 +buffer to be reallocated in order to accommodate the new data. As a
1.3128 +result, MaxLength() and Ptr() may return different values afterwards,
1.3129 +and any existing raw pointers to into the descriptor data may be
1.3130 +invalidated.
1.3131 +
1.3132 +@param aZeroTerminatedString A 8-bit zero terminated string.
1.3133 +
1.3134 +@leave KErrNoMemory if the underlying buffer needs to be
1.3135 +grown and there are insufficient resources to do so
1.3136 +*/
1.3137 +EXPORT_C void LString8:: CopyLCL(const TUint8* aZeroTerminatedString)
1.3138 + {
1.3139 + LString8::CopyLCL(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.3140 + }
1.3141 +
1.3142 +/**
1.3143 +Copies text from the specified string and converts it to upper case before
1.3144 +putting it into this descriptor, replacing any existing data.
1.3145 +
1.3146 +The length of this descriptor is set to reflect the new data.
1.3147 +
1.3148 +Conversion to upper case is implemented as appropriate to the current locale.
1.3149 +
1.3150 +This leaving variant of the standard, non-leaving descriptor method
1.3151 +differs in that this operation may cause the string descriptor's heap
1.3152 +buffer to be reallocated in order to accommodate the new data. As a
1.3153 +result, MaxLength() and Ptr() may return different values afterwards,
1.3154 +and any existing raw pointers to into the descriptor data may be
1.3155 +invalidated.
1.3156 +
1.3157 +@param aCharStr A 8-bit character string.
1.3158 +
1.3159 +@leave KErrNoMemory if the underlying buffer needs to be
1.3160 +grown and there are insufficient resources to do so
1.3161 +*/
1.3162 +EXPORT_C void LString8:: CopyUCL(const char* aCharStr)
1.3163 + {
1.3164 + LString8::CopyUCL(reinterpret_cast<const TUint8*>(aCharStr));
1.3165 + }
1.3166 +
1.3167 +/**
1.3168 +Copies text from the specified string and converts it to upper case before
1.3169 +putting it into this descriptor, replacing any existing data.
1.3170 +
1.3171 +The length of this descriptor is set to reflect the new data.
1.3172 +
1.3173 +Conversion to upper case is implemented as appropriate to the current locale.
1.3174 +
1.3175 +This leaving variant of the standard, non-leaving descriptor method
1.3176 +differs in that this operation may cause the string descriptor's heap
1.3177 +buffer to be reallocated in order to accommodate the new data. As a
1.3178 +result, MaxLength() and Ptr() may return different values afterwards,
1.3179 +and any existing raw pointers to into the descriptor data may be
1.3180 +invalidated.
1.3181 +
1.3182 +@param aZeroTerminatedString A 8-bit zero terminated string.
1.3183 +
1.3184 +@leave KErrNoMemory if the underlying buffer needs to be
1.3185 +grown and there are insufficient resources to do so
1.3186 +*/
1.3187 +EXPORT_C void LString8:: CopyUCL(const TUint8* aZeroTerminatedString)
1.3188 + {
1.3189 + LString8::CopyUCL(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.3190 + }
1.3191 +
1.3192 +/**
1.3193 +Copies text from the specified string and capitalises it before putting
1.3194 +it into this descriptor, replacing any existing data.
1.3195 +
1.3196 +The length of this descriptor is set to reflect the new data.
1.3197 +
1.3198 +Capitalisation is implemented as appropriate to the current locale.
1.3199 +
1.3200 +This leaving variant of the standard, non-leaving descriptor method
1.3201 +differs in that this operation may cause the string descriptor's heap
1.3202 +buffer to be reallocated in order to accommodate the new data. As a
1.3203 +result, MaxLength() and Ptr() may return different values afterwards,
1.3204 +and any existing raw pointers to into the descriptor data may be
1.3205 +invalidated.
1.3206 +
1.3207 +@param aCharStr A 8-bit character string.
1.3208 +
1.3209 +@leave KErrNoMemory if the underlying buffer needs to be
1.3210 +grown and there are insufficient resources to do so
1.3211 +*/
1.3212 +EXPORT_C void LString8:: CopyCPL(const char* aCharStr)
1.3213 + {
1.3214 + LString8::CopyCPL(reinterpret_cast<const TUint8*>(aCharStr));
1.3215 + }
1.3216 +
1.3217 +/**
1.3218 +Copies text from the specified string and capitalises it before putting
1.3219 +it into this descriptor, replacing any existing data.
1.3220 +
1.3221 +The length of this descriptor is set to reflect the new data.
1.3222 +
1.3223 +Capitalisation is implemented as appropriate to the current locale.
1.3224 +
1.3225 +This leaving variant of the standard, non-leaving descriptor method
1.3226 +differs in that this operation may cause the string descriptor's heap
1.3227 +buffer to be reallocated in order to accommodate the new data. As a
1.3228 +result, MaxLength() and Ptr() may return different values afterwards,
1.3229 +and any existing raw pointers to into the descriptor data may be
1.3230 +invalidated.
1.3231 +
1.3232 +@param aZeroTerminatedString A 8-bit zero terminated string.
1.3233 +
1.3234 +@leave KErrNoMemory if the underlying buffer needs to be
1.3235 +grown and there are insufficient resources to do so
1.3236 +*/
1.3237 +EXPORT_C void LString8:: CopyCPL(const TUint8* aZeroTerminatedString)
1.3238 + {
1.3239 + LString8::CopyCPL(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.3240 + }
1.3241 +/**
1.3242 +Inserts data into this descriptor.
1.3243 +
1.3244 +The length of this descriptor is changed to reflect the extra data.
1.3245 +
1.3246 +This leaving variant of the standard, non-leaving descriptor method
1.3247 +differs in that this operation may cause the string descriptor's heap
1.3248 +buffer to be reallocated in order to accommodate the new data. As a
1.3249 +result, MaxLength() and Ptr() may return different values afterwards,
1.3250 +and any existing raw pointers to into the descriptor data may be
1.3251 +invalidated.
1.3252 +
1.3253 +@param aPos The position within the data where insertion is to start. This
1.3254 + is an offset value; a zero value refers to the leftmost data
1.3255 + position.
1.3256 +
1.3257 +@param aCharStr A 8-bit character string.
1.3258 +
1.3259 +@leave KErrNoMemory if the underlying buffer needs to be
1.3260 +grown and there are insufficient resources to do so
1.3261 +
1.3262 +@panic USER 10 if aPos is negative or is greater than the length of this
1.3263 + descriptor.
1.3264 +*/
1.3265 +EXPORT_C void LString8:: InsertL(TInt aPos,const char* aCharStr)
1.3266 + {
1.3267 + LString8::InsertL(aPos, reinterpret_cast<const TUint8*>(aCharStr));
1.3268 + }
1.3269 +
1.3270 +/**
1.3271 +Inserts data into this descriptor.
1.3272 +
1.3273 +The length of this descriptor is changed to reflect the extra data.
1.3274 +
1.3275 +This leaving variant of the standard, non-leaving descriptor method
1.3276 +differs in that this operation may cause the string descriptor's heap
1.3277 +buffer to be reallocated in order to accommodate the new data. As a
1.3278 +result, MaxLength() and Ptr() may return different values afterwards,
1.3279 +and any existing raw pointers to into the descriptor data may be
1.3280 +invalidated.
1.3281 +
1.3282 +@param aPos The position within the data where insertion is to start. This
1.3283 + is an offset value; a zero value refers to the leftmost data
1.3284 + position.
1.3285 +
1.3286 +@param aZeroTerminatedString A 8-bit null terminated string.
1.3287 +
1.3288 +@leave KErrNoMemory if the underlying buffer needs to be
1.3289 +grown and there are insufficient resources to do so
1.3290 +
1.3291 +@panic USER 10 if aPos is negative or is greater than the length of this
1.3292 + descriptor.
1.3293 +*/
1.3294 +EXPORT_C void LString8:: InsertL(TInt aPos,const TUint8* aZeroTerminatedString)
1.3295 + {
1.3296 + LString8::InsertL(aPos,TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.3297 + }
1.3298 +
1.3299 +/**
1.3300 +Replaces data in this descriptor.
1.3301 +
1.3302 +The specified length can be different to the length of the replacement data.
1.3303 +The length of this descriptor changes to reflect the change of data.
1.3304 +
1.3305 +This leaving variant of the standard, non-leaving descriptor method
1.3306 +differs in that this operation may cause the string descriptor's heap
1.3307 +buffer to be reallocated in order to accommodate the new data. As a
1.3308 +result, MaxLength() and Ptr() may return different values afterwards,
1.3309 +and any existing raw pointers to into the descriptor data may be
1.3310 +invalidated.
1.3311 +
1.3312 +@param aPos The position within the data where replacement is to start.
1.3313 + This is an offset value; a zero value refers to the leftmost
1.3314 + data position.
1.3315 +
1.3316 +@param aLength The length of data to be replaced.
1.3317 +
1.3318 +@param aCharStr The source 8-bit character string
1.3319 +
1.3320 +@leave KErrNoMemory if the underlying buffer needs to be
1.3321 +grown and there are insufficient resources to do so
1.3322 +
1.3323 +@panic USER 8 if aLength is negative
1.3324 +
1.3325 +@panic USER 10 if aPos is negative or is greater than the length of this
1.3326 + descriptor.
1.3327 +
1.3328 +@panic USER 16 if the length of the source descriptor aDes is negative
1.3329 +*/
1.3330 +EXPORT_C void LString8:: ReplaceL(TInt aPos,TInt aLength,const char* aCharStr)
1.3331 + {
1.3332 + LString8::ReplaceL(aPos,aLength,reinterpret_cast<const TUint8*>(aCharStr));
1.3333 + }
1.3334 +
1.3335 +/**
1.3336 +Replaces data in this descriptor.
1.3337 +
1.3338 +The specified length can be different to the length of the replacement data.
1.3339 +The length of this descriptor changes to reflect the change of data.
1.3340 +
1.3341 +This leaving variant of the standard, non-leaving descriptor method
1.3342 +differs in that this operation may cause the string descriptor's heap
1.3343 +buffer to be reallocated in order to accommodate the new data. As a
1.3344 +result, MaxLength() and Ptr() may return different values afterwards,
1.3345 +and any existing raw pointers to into the descriptor data may be
1.3346 +invalidated.
1.3347 +
1.3348 +@param aPos The position within the data where replacement is to start.
1.3349 + This is an offset value; a zero value refers to the leftmost
1.3350 + data position.
1.3351 +
1.3352 +@param aLength The length of data to be replaced.
1.3353 +
1.3354 +@param aZeroTerminatedString The source 8-bit null terminated character string
1.3355 +
1.3356 +@leave KErrNoMemory if the underlying buffer needs to be
1.3357 +grown and there are insufficient resources to do so
1.3358 +
1.3359 +@panic USER 8 if aLength is negative
1.3360 +
1.3361 +@panic USER 10 if aPos is negative or is greater than the length of this
1.3362 + descriptor.
1.3363 +
1.3364 +@panic USER 16 if the length of the source descriptor aDes is negative
1.3365 +*/
1.3366 +EXPORT_C void LString8:: ReplaceL(TInt aPos,TInt aLength,const TUint8* aZeroTerminatedString)
1.3367 + {
1.3368 + LString8::ReplaceL(aPos,aLength,TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)));
1.3369 + }
1.3370 +
1.3371 +/**
1.3372 +Copies data into this descriptor and justifies it, replacing any existing data.
1.3373 +
1.3374 +The length of this descriptor is set to reflect the new data.
1.3375 +
1.3376 +The target area is considered to be an area of specified width positioned at
1.3377 +the beginning of this descriptor's data area. Source data is copied into, and
1.3378 +aligned within this target area according to the specified alignment
1.3379 +instruction.
1.3380 +
1.3381 +If the length of the target area is larger than the length of the source, then
1.3382 +spare space within the target area is padded with the fill character.
1.3383 +
1.3384 +This leaving variant of the standard, non-leaving descriptor method
1.3385 +differs in that this operation may cause the string descriptor's heap
1.3386 +buffer to be reallocated in order to accommodate the new data. As a
1.3387 +result, MaxLength() and Ptr() may return different values afterwards,
1.3388 +and any existing raw pointers to into the descriptor data may be
1.3389 +invalidated.
1.3390 +
1.3391 +@param aCharStr A 8-bit character string containing the source data.
1.3392 + The length of the data to be copied is the smaller of:
1.3393 + the length of the source descriptor, and
1.3394 + the width of the target area (only if this is not the
1.3395 + explicit negative value KDefaultJustifyWidth).
1.3396 +
1.3397 +@param aWidth The width of the target area. If this has the specific
1.3398 + negative value KDefaultJustifyWidth, then the width is
1.3399 + re-set to the length of the data source.
1.3400 +
1.3401 +@param aAlignment The alignment of the data within the target area
1.3402 +
1.3403 +@param aFill The fill character used to pad the target area.
1.3404 +
1.3405 +@leave KErrNoMemory if the underlying buffer needs to be
1.3406 +grown and there are insufficient resources to do so
1.3407 +
1.3408 +@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
1.3409 +*/
1.3410 +EXPORT_C void LString8:: JustifyL(const char* aCharStr,TInt aWidth,TAlign anAlignment,TChar aFill)
1.3411 + {
1.3412 + LString8::JustifyL(reinterpret_cast<const TUint8*>(aCharStr),aWidth,anAlignment,aFill);
1.3413 + }
1.3414 +
1.3415 +/**
1.3416 +Copies data into this descriptor and justifies it, replacing any existing data.
1.3417 +
1.3418 +The length of this descriptor is set to reflect the new data.
1.3419 +
1.3420 +The target area is considered to be an area of specified width positioned at
1.3421 +the beginning of this descriptor's data area. Source data is copied into, and
1.3422 +aligned within this target area according to the specified alignment
1.3423 +instruction.
1.3424 +
1.3425 +If the length of the target area is larger than the length of the source, then
1.3426 +spare space within the target area is padded with the fill character.
1.3427 +
1.3428 +This leaving variant of the standard, non-leaving descriptor method
1.3429 +differs in that this operation may cause the string descriptor's heap
1.3430 +buffer to be reallocated in order to accommodate the new data. As a
1.3431 +result, MaxLength() and Ptr() may return different values afterwards,
1.3432 +and any existing raw pointers to into the descriptor data may be
1.3433 +invalidated.
1.3434 +
1.3435 +@param aCharStr A 8-bit character string containing the source data.
1.3436 + The length of the data to be copied is the smaller of:
1.3437 + the length of the source descriptor, and
1.3438 + the width of the target area (only if this is not the
1.3439 + explicit negative value KDefaultJustifyWidth).
1.3440 +
1.3441 +@param aWidth The width of the target area. If this has the specific
1.3442 + negative value KDefaultJustifyWidth, then the width is
1.3443 + re-set to the length of the data source.
1.3444 +
1.3445 +@param aAlignment The alignment of the data within the target area
1.3446 +
1.3447 +@param aFill The fill character used to pad the target area.
1.3448 +
1.3449 +@leave KErrNoMemory if the underlying buffer needs to be
1.3450 +grown and there are insufficient resources to do so
1.3451 +
1.3452 +@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
1.3453 +*/
1.3454 +EXPORT_C void LString8:: JustifyL(const TUint8* aZeroTerminatedString,TInt aWidth,TAlign anAlignment,TChar aFill)
1.3455 + {
1.3456 + LString8::JustifyL(TPtrC8((aZeroTerminatedString), User::StringLength(aZeroTerminatedString)),aWidth,anAlignment,aFill);
1.3457 + }
1.3458 +
1.3459 +/**
1.3460 +Appends data onto the end of this descriptor's data and justifies it.
1.3461 +
1.3462 +The source of the appended data is a memory location.
1.3463 +
1.3464 +The target area is considered to be an area of specified width, immediately
1.3465 +following this descriptor's existing data. Source data is copied into, and
1.3466 +aligned within, this target area according to the specified alignment instruction.
1.3467 +
1.3468 +If the length of the target area is larger than the length of the source,
1.3469 +then spare space within the target area is padded with the fill character.
1.3470 +
1.3471 +This leaving variant of the standard, non-leaving descriptor method
1.3472 +differs in that this operation may cause the string descriptor's heap
1.3473 +buffer to be reallocated in order to accommodate the new data. As a
1.3474 +result, MaxLength() and Ptr() may return different values afterwards,
1.3475 +and any existing raw pointers to into the descriptor data may be
1.3476 +invalidated.
1.3477 +
1.3478 +@param aString A pointer to a source memory location.
1.3479 +
1.3480 +@param aLength The length of data to be copied. If this is greater than the
1.3481 + width of the target area, then the length of data copied is
1.3482 + limited to the width.
1.3483 +
1.3484 +@param aWidth The width of the target area. If this has the specific negative
1.3485 + value KDefaultJustifyWidth, then the width is
1.3486 + re-set to the length of the data source.
1.3487 +
1.3488 +@param aAlignment The alignment of the data within the target area.
1.3489 +
1.3490 +@param aFill The fill character used to pad the target area.
1.3491 +
1.3492 +@leave KErrNoMemory if the underlying buffer needs to be
1.3493 +grown and there are insufficient resources to do so
1.3494 +
1.3495 +@panic USER 11 if aWidth has a negative value other than KDefaultJustifyWidth.
1.3496 +
1.3497 +@panic USER 17 if aLength is negative.
1.3498 +*/
1.3499 +EXPORT_C void LString8:: AppendJustifyL(const char* aCharStr,TInt aLength,TInt aWidth,TAlign anAlignment,TChar aFill)
1.3500 + {
1.3501 + LString8::AppendJustifyL(reinterpret_cast<const TUint8*>(aCharStr),aLength, aWidth,anAlignment,aFill);
1.3502 + }
1.3503 +
1.3504 +// eof